mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2024-12-22 06:25:12 +01:00
Documentation Improvements (#3214, #3217, #3218, #3271, #3289, #3292, #3303, #3312, #3306, #3319, #3326, #3314)
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Simon Fong <44134941+simonfongnt@users.noreply.github.com> Co-authored-by: Piotr Rogulski <rivinek@gmail.com> Co-authored-by: poolitzer <25934244+Poolitzer@users.noreply.github.com> Co-authored-by: Or Bin <or@raftt.io> Co-authored-by: Sandro <j32g7f67hb@liamekaens.com> Co-authored-by: Hatim Zahid <63000127+HatimZ@users.noreply.github.com> Co-authored-by: Robi <53259730+RobiMez@users.noreply.github.com> Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi
GitHub
parent
70aa674226
commit
9520c6eeba
70 changed files with 1104 additions and 2095 deletions
2
.github/CONTRIBUTING.rst
vendored
2
.github/CONTRIBUTING.rst
vendored
|
|
@ -13,7 +13,7 @@ Setting things up
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone https://github.com/<your username>/python-telegram-bot --recursive
|
||||
$ git clone https://github.com/<your username>/python-telegram-bot
|
||||
$ cd python-telegram-bot
|
||||
|
||||
3. Add a track to the original repository:
|
||||
|
|
|
|||
|
|
@ -21,6 +21,31 @@ python:
|
|||
- requirements: docs/requirements-docs.txt
|
||||
|
||||
build:
|
||||
os: ubuntu-20.04
|
||||
os: ubuntu-22.04
|
||||
tools:
|
||||
python: "3" # latest stable cpython version
|
||||
|
||||
search:
|
||||
ranking: # bump up rank of commonly searched pages: (default: 0, values range from -10 to 10)
|
||||
telegram.bot.html: 7
|
||||
telegram.message.html: 3
|
||||
telegram.update.html: 3
|
||||
telegram.user.html: 2
|
||||
telegram.chat.html: 2
|
||||
telegram.ext.application.html: 3
|
||||
telegram.ext.filters.html: 3
|
||||
telegram.ext.callbackcontext.html: 2
|
||||
telegram.ext.inlinekeyboardbutton.html: 1
|
||||
|
||||
telegram.passport*.html: -7
|
||||
|
||||
ignore:
|
||||
- changelog.html
|
||||
- coc.html
|
||||
- bot_methods.html#
|
||||
- bot_methods.html
|
||||
# Defaults
|
||||
- search.html
|
||||
- search/index.html
|
||||
- 404.html
|
||||
- 404/index.html'
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
sphinx==5.3.0
|
||||
sphinx-pypi-upload
|
||||
furo==2022.9.29
|
||||
git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search
|
||||
sphinx-paramlinks==0.5.4
|
||||
sphinxcontrib-mermaid==0.7.1
|
||||
|
|
@ -5,7 +5,7 @@ import subprocess
|
|||
import sys
|
||||
from enum import Enum
|
||||
from pathlib import Path
|
||||
from typing import Tuple
|
||||
from typing import List, Tuple
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
|
|
@ -34,7 +34,7 @@ version = "20.0a4" # telegram.__version__[:3]
|
|||
release = "20.0a4" # telegram.__version__
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
needs_sphinx = "4.5.0"
|
||||
needs_sphinx = "5.1.1"
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
|
|
@ -46,6 +46,7 @@ extensions = [
|
|||
"sphinx.ext.linkcode",
|
||||
"sphinx_paramlinks",
|
||||
"sphinxcontrib.mermaid",
|
||||
"sphinx_search.extension",
|
||||
]
|
||||
|
||||
# Use intersphinx to reference the python builtin library docs
|
||||
|
|
@ -215,11 +216,9 @@ html_favicon = "ptb-logo_1024.ico"
|
|||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ["_static"]
|
||||
html_css_files = [
|
||||
"style_external_link.css",
|
||||
"style_mermaid_diagrams.css",
|
||||
]
|
||||
html_permalinks_icon = "¶" # Furo's default permalink icon is `#`` which doesn't look great imo.
|
||||
html_css_files = ["style_external_link.css", "style_mermaid_diagrams.css"]
|
||||
|
||||
html_permalinks_icon = "¶" # Furo's default permalink icon is `#` which doesn't look great imo.
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = "python-telegram-bot-doc"
|
||||
|
|
@ -260,6 +259,7 @@ latex_logo = "ptb-logo_1024.png"
|
|||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)]
|
||||
|
||||
# rtd_sphinx_search_file_type = "un-minified" # Configuration for furo-sphinx-search
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
|
|
@ -378,12 +378,98 @@ line_numbers = {}
|
|||
file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
|
||||
import telegram.ext # Needed for checking if an object is a BaseFilter
|
||||
|
||||
keyword_args = [
|
||||
":keyword _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to {read_timeout}.",
|
||||
":kwtype _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: {read_timeout_type}, optional",
|
||||
":keyword _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to {write_timeout}.",
|
||||
":kwtype _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: :obj:`float` | :obj:`None`, optional",
|
||||
":keyword _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
|
||||
":kwtype _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: :obj:`float` | :obj:`None`, optional",
|
||||
":keyword _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
|
||||
":kwtype _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: :obj:`float` | :obj:`None`, optional",
|
||||
":keyword _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: Arbitrary keyword arguments to be passed to the Telegram API.",
|
||||
":kwtype _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: :obj:`dict`, optional",
|
||||
"",
|
||||
]
|
||||
|
||||
def autodoc_process_docstring(app: Sphinx, what, name: str, obj: object, options, lines):
|
||||
"""We misuse this autodoc hook to get the file names & line numbers because we have access
|
||||
to the actual object here.
|
||||
write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"]
|
||||
read_timeout_sub = [
|
||||
":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
|
||||
"``2``. :paramref:`timeout` will be added to this value",
|
||||
]
|
||||
read_timeout_type = [":obj:`float` | :obj:`None`", ":obj:`float`"]
|
||||
|
||||
|
||||
def find_insert_pos(lines: List[str]) -> int:
|
||||
"""Finds the correct position to insert the keyword arguments and returns the index."""
|
||||
for idx, value in reversed(list(enumerate(lines))): # reversed since :returns: is at the end
|
||||
if value.startswith(":returns:"):
|
||||
return idx
|
||||
else:
|
||||
return False
|
||||
|
||||
|
||||
def is_write_timeout_20(obj: object) -> int:
|
||||
"""inspects the default value of write_timeout parameter of the bot method."""
|
||||
sig = inspect.signature(obj)
|
||||
return 1 if (sig.parameters["write_timeout"].default == 20) else 0
|
||||
|
||||
|
||||
def check_timeout_and_api_kwargs_presence(obj: object) -> int:
|
||||
"""Checks if the method has timeout and api_kwargs keyword only parameters."""
|
||||
sig = inspect.signature(obj)
|
||||
params_to_check = (
|
||||
"read_timeout",
|
||||
"write_timeout",
|
||||
"connect_timeout",
|
||||
"pool_timeout",
|
||||
"api_kwargs",
|
||||
)
|
||||
return all(
|
||||
param in sig.parameters and sig.parameters[param].kind == inspect.Parameter.KEYWORD_ONLY
|
||||
for param in params_to_check
|
||||
)
|
||||
|
||||
|
||||
def autodoc_process_docstring(
|
||||
app: Sphinx, what, name: str, obj: object, options, lines: List[str]
|
||||
):
|
||||
"""We do two things:
|
||||
1) Use this method to automatically insert the Keyword Args for the Bot methods.
|
||||
|
||||
2) Misuse this autodoc hook to get the file names & line numbers because we have access
|
||||
to the actual object here.
|
||||
"""
|
||||
# Ce can't properly handle ordinary attributes.
|
||||
# 1) Insert the Keyword Args for the Bot methods
|
||||
method_name = name.split(".")[-1]
|
||||
if (
|
||||
name.startswith("telegram.Bot.")
|
||||
and what == "method"
|
||||
and method_name.islower()
|
||||
and check_timeout_and_api_kwargs_presence(obj)
|
||||
):
|
||||
insert_index = find_insert_pos(lines)
|
||||
if not insert_index:
|
||||
raise ValueError(
|
||||
f"Couldn't find the correct position to insert the keyword args for {obj}."
|
||||
)
|
||||
|
||||
long_write_timeout = is_write_timeout_20(obj)
|
||||
get_updates_sub = 1 if (method_name == "get_updates") else 0
|
||||
# The below can be done in 1 line with itertools.chain, but this must be modified in-place
|
||||
for i in range(insert_index, insert_index + len(keyword_args)):
|
||||
lines.insert(
|
||||
i,
|
||||
keyword_args[i - insert_index].format(
|
||||
method=method_name,
|
||||
write_timeout=write_timeout_sub[long_write_timeout],
|
||||
read_timeout=read_timeout_sub[get_updates_sub],
|
||||
read_timeout_type=read_timeout_type[get_updates_sub],
|
||||
),
|
||||
)
|
||||
|
||||
# 2) Get the file names & line numbers
|
||||
# We can't properly handle ordinary attributes.
|
||||
# In linkcode_resolve we'll resolve to the `__init__` or module instead
|
||||
if what == "attribute":
|
||||
return
|
||||
|
|
|
|||
7
docs/source/inclusions/application_run_tip.rst
Normal file
7
docs/source/inclusions/application_run_tip.rst
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
.. tip::
|
||||
When combining ``python-telegram-bot`` with other :mod:`asyncio` based frameworks, using this
|
||||
method is likely not the best choice, as it blocks the event loop until it receives a stop
|
||||
signal as described above.
|
||||
Instead, you can manually call the methods listed below to start and shut down the application
|
||||
and the :attr:`~telegram.ext.Application.updater`.
|
||||
Keeping the event loop running and listening for a stop signal is then up to you.
|
||||
|
|
@ -290,6 +290,10 @@
|
|||
:align: left
|
||||
:widths: 1 4
|
||||
|
||||
* - :attr:`~telegram.Bot.base_file_url`
|
||||
- Telegram Bot API file URL
|
||||
* - :attr:`~telegram.Bot.base_url`
|
||||
- Telegram Bot API service URL
|
||||
* - :attr:`~telegram.Bot.bot`
|
||||
- The user instance of the bot as returned by :meth:`~telegram.Bot.get_me`
|
||||
* - :attr:`~telegram.Bot.can_join_groups`
|
||||
|
|
@ -310,8 +314,12 @@
|
|||
- The username of the bot, without leading ``@``
|
||||
* - :attr:`~telegram.Bot.link`
|
||||
- The t.me link of the bot
|
||||
* - :attr:`~telegram.Bot.private_key`
|
||||
- Deserialized private key for decryption of telegram passport data
|
||||
* - :attr:`~telegram.Bot.supports_inline_queries`
|
||||
- Whether the bot supports inline queries
|
||||
* - :attr:`~telegram.Bot.token`
|
||||
- Bot's unique authentication token
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
|
|
|||
82
docs/source/telegram.at-tree.rst
Normal file
82
docs/source/telegram.at-tree.rst
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
Available Types
|
||||
---------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telegram.animation
|
||||
telegram.audio
|
||||
telegram.botcommand
|
||||
telegram.botcommandscope
|
||||
telegram.botcommandscopeallchatadministrators
|
||||
telegram.botcommandscopeallgroupchats
|
||||
telegram.botcommandscopeallprivatechats
|
||||
telegram.botcommandscopechat
|
||||
telegram.botcommandscopechatadministrators
|
||||
telegram.botcommandscopechatmember
|
||||
telegram.botcommandscopedefault
|
||||
telegram.callbackquery
|
||||
telegram.chat
|
||||
telegram.chatadministratorrights
|
||||
telegram.chatinvitelink
|
||||
telegram.chatjoinrequest
|
||||
telegram.chatlocation
|
||||
telegram.chatmember
|
||||
telegram.chatmemberadministrator
|
||||
telegram.chatmemberbanned
|
||||
telegram.chatmemberleft
|
||||
telegram.chatmembermember
|
||||
telegram.chatmemberowner
|
||||
telegram.chatmemberrestricted
|
||||
telegram.chatmemberupdated
|
||||
telegram.chatpermissions
|
||||
telegram.chatphoto
|
||||
telegram.contact
|
||||
telegram.dice
|
||||
telegram.document
|
||||
telegram.file
|
||||
telegram.forcereply
|
||||
telegram.inlinekeyboardbutton
|
||||
telegram.inlinekeyboardmarkup
|
||||
telegram.inputfile
|
||||
telegram.inputmedia
|
||||
telegram.inputmediaanimation
|
||||
telegram.inputmediaaudio
|
||||
telegram.inputmediadocument
|
||||
telegram.inputmediaphoto
|
||||
telegram.inputmediavideo
|
||||
telegram.keyboardbutton
|
||||
telegram.keyboardbuttonpolltype
|
||||
telegram.location
|
||||
telegram.loginurl
|
||||
telegram.menubutton
|
||||
telegram.menubuttoncommands
|
||||
telegram.menubuttondefault
|
||||
telegram.menubuttonwebapp
|
||||
telegram.message
|
||||
telegram.messageautodeletetimerchanged
|
||||
telegram.messageentity
|
||||
telegram.messageid
|
||||
telegram.photosize
|
||||
telegram.poll
|
||||
telegram.pollanswer
|
||||
telegram.polloption
|
||||
telegram.proximityalerttriggered
|
||||
telegram.replykeyboardmarkup
|
||||
telegram.replykeyboardremove
|
||||
telegram.sentwebappmessage
|
||||
telegram.telegramobject
|
||||
telegram.update
|
||||
telegram.user
|
||||
telegram.userprofilephotos
|
||||
telegram.venue
|
||||
telegram.video
|
||||
telegram.videochatended
|
||||
telegram.videochatparticipantsinvited
|
||||
telegram.videochatscheduled
|
||||
telegram.videochatstarted
|
||||
telegram.videonote
|
||||
telegram.voice
|
||||
telegram.webappdata
|
||||
telegram.webappinfo
|
||||
telegram.webhookinfo
|
||||
|
||||
|
|
@ -2,6 +2,7 @@ telegram.ext package
|
|||
====================
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
|
||||
telegram.ext.application
|
||||
telegram.ext.applicationbuilder
|
||||
|
|
|
|||
|
|
@ -7,88 +7,14 @@ Version Constants
|
|||
.. automodule:: telegram
|
||||
:members: __version__, __version_info__, __bot_api_version__, __bot_api_version_info__
|
||||
|
||||
Available Types
|
||||
---------------
|
||||
Classes in this package
|
||||
-----------------------
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
|
||||
telegram.animation
|
||||
telegram.audio
|
||||
telegram.bot
|
||||
telegram.botcommand
|
||||
telegram.botcommandscope
|
||||
telegram.botcommandscopeallchatadministrators
|
||||
telegram.botcommandscopeallgroupchats
|
||||
telegram.botcommandscopeallprivatechats
|
||||
telegram.botcommandscopechat
|
||||
telegram.botcommandscopechatadministrators
|
||||
telegram.botcommandscopechatmember
|
||||
telegram.botcommandscopedefault
|
||||
telegram.callbackquery
|
||||
telegram.chat
|
||||
telegram.chatadministratorrights
|
||||
telegram.chatinvitelink
|
||||
telegram.chatjoinrequest
|
||||
telegram.chatlocation
|
||||
telegram.chatmember
|
||||
telegram.chatmemberadministrator
|
||||
telegram.chatmemberbanned
|
||||
telegram.chatmemberleft
|
||||
telegram.chatmembermember
|
||||
telegram.chatmemberowner
|
||||
telegram.chatmemberrestricted
|
||||
telegram.chatmemberupdated
|
||||
telegram.chatpermissions
|
||||
telegram.chatphoto
|
||||
telegram.contact
|
||||
telegram.dice
|
||||
telegram.document
|
||||
telegram.file
|
||||
telegram.forcereply
|
||||
telegram.inlinekeyboardbutton
|
||||
telegram.inlinekeyboardmarkup
|
||||
telegram.inputfile
|
||||
telegram.inputmedia
|
||||
telegram.inputmediaanimation
|
||||
telegram.inputmediaaudio
|
||||
telegram.inputmediadocument
|
||||
telegram.inputmediaphoto
|
||||
telegram.inputmediavideo
|
||||
telegram.keyboardbutton
|
||||
telegram.keyboardbuttonpolltype
|
||||
telegram.location
|
||||
telegram.loginurl
|
||||
telegram.menubutton
|
||||
telegram.menubuttoncommands
|
||||
telegram.menubuttondefault
|
||||
telegram.menubuttonwebapp
|
||||
telegram.message
|
||||
telegram.messageautodeletetimerchanged
|
||||
telegram.messageentity
|
||||
telegram.messageid
|
||||
telegram.photosize
|
||||
telegram.poll
|
||||
telegram.pollanswer
|
||||
telegram.polloption
|
||||
telegram.proximityalerttriggered
|
||||
telegram.replykeyboardmarkup
|
||||
telegram.replykeyboardremove
|
||||
telegram.sentwebappmessage
|
||||
telegram.telegramobject
|
||||
telegram.update
|
||||
telegram.user
|
||||
telegram.userprofilephotos
|
||||
telegram.venue
|
||||
telegram.video
|
||||
telegram.videochatended
|
||||
telegram.videochatparticipantsinvited
|
||||
telegram.videochatscheduled
|
||||
telegram.videochatstarted
|
||||
telegram.videonote
|
||||
telegram.voice
|
||||
telegram.webappdata
|
||||
telegram.webappinfo
|
||||
telegram.webhookinfo
|
||||
telegram.at-tree.rst
|
||||
telegram.stickers-tree.rst
|
||||
telegram.inline-tree.rst
|
||||
telegram.payments-tree.rst
|
||||
|
|
|
|||
|
|
@ -4,4 +4,4 @@ telegram.TelegramObject
|
|||
.. autoclass:: telegram.TelegramObject
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:special-members: __repr__
|
||||
:special-members: __repr__, __getitem__, __eq__, __hash__, __setstate__, __getstate__, __deepcopy__
|
||||
|
|
|
|||
|
|
@ -21,3 +21,19 @@
|
|||
.. |toapikwargsarg| replace:: Arbitrary keyword arguments. Can be used to store data for which there are no dedicated attributes. |toapikwargsbase|
|
||||
|
||||
.. |toapikwargsattr| replace:: Optional. Arbitrary keyword arguments. Used to store data for which there are no dedicated attributes. |toapikwargsbase|
|
||||
|
||||
.. |chat_id_channel| replace:: Unique identifier for the target chat or username of the target channel (in the format ``@channelusername``).
|
||||
|
||||
.. |chat_id_group| replace:: Unique identifier for the target chat or username of the target supergroup (in the format ``@supergroupusername``).
|
||||
|
||||
.. |parse_mode| replace:: Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message. See the constants in :class:`telegram.constants.ParseMode` for the available modes.
|
||||
|
||||
.. |allow_sending_without_reply| replace:: Pass :obj:`True`, if the message should be sent even if the specified replied-to message is not found.
|
||||
|
||||
.. |caption_entities| replace:: List of special entities that appear in the caption, which can be specified instead of ``parse_mode``.
|
||||
|
||||
.. |protect_content| replace:: Protects the contents of the sent message from forwarding and saving.
|
||||
|
||||
.. |disable_notification| replace:: Sends the message silently. Users will receive a notification with no sound.
|
||||
|
||||
.. |reply_to_msg_id| replace:: If the message is a reply, ID of the original message.
|
||||
2011
telegram/_bot.py
2011
telegram/_bot.py
File diff suppressed because it is too large
Load diff
|
|
@ -182,12 +182,11 @@ class BotCommandScopeChat(BotCommandScope):
|
|||
.. versionadded:: 13.7
|
||||
|
||||
Args:
|
||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
||||
target supergroup (in the format ``@supergroupusername``)
|
||||
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||
|
||||
Attributes:
|
||||
type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT`.
|
||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
||||
target supergroup (in the format ``@supergroupusername``)
|
||||
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||
"""
|
||||
|
||||
__slots__ = ("chat_id",)
|
||||
|
|
@ -210,12 +209,10 @@ class BotCommandScopeChatAdministrators(BotCommandScope):
|
|||
.. versionadded:: 13.7
|
||||
|
||||
Args:
|
||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
||||
target supergroup (in the format ``@supergroupusername``)
|
||||
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||
Attributes:
|
||||
type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_ADMINISTRATORS`.
|
||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
||||
target supergroup (in the format ``@supergroupusername``)
|
||||
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||
"""
|
||||
|
||||
__slots__ = ("chat_id",)
|
||||
|
|
@ -238,14 +235,12 @@ class BotCommandScopeChatMember(BotCommandScope):
|
|||
.. versionadded:: 13.7
|
||||
|
||||
Args:
|
||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
||||
target supergroup (in the format ``@supergroupusername``)
|
||||
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||
user_id (:obj:`int`): Unique identifier of the target user.
|
||||
|
||||
Attributes:
|
||||
type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_MEMBER`.
|
||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
||||
target supergroup (in the format ``@supergroupusername``)
|
||||
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||
user_id (:obj:`int`): Unique identifier of the target user.
|
||||
"""
|
||||
|
||||
|
|
|
|||
|
|
@ -149,21 +149,28 @@ class Chat(TelegramObject):
|
|||
|
||||
.. versionadded:: 20.0
|
||||
Attributes:
|
||||
id (:obj:`int`): Unique identifier for this chat.
|
||||
type (:obj:`str`): Type of chat.
|
||||
id (:obj:`int`): Unique identifier for this chat. This number may be greater than 32 bits
|
||||
and some programming languages may have difficulty/silent defects in interpreting it.
|
||||
But it is smaller than 52 bits, so a signed 64-bit integer or double-precision float
|
||||
type are safe for storing this identifier.
|
||||
type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
|
||||
:attr:`SUPERGROUP` or :attr:`CHANNEL`.
|
||||
title (:obj:`str`): Optional. Title, for supergroups, channels and group chats.
|
||||
username (:obj:`str`): Optional. Username.
|
||||
username (:obj:`str`): Optional. Username, for private chats, supergroups and channels if
|
||||
available.
|
||||
first_name (:obj:`str`): Optional. First name of the other party in a private chat.
|
||||
last_name (:obj:`str`): Optional. Last name of the other party in a private chat.
|
||||
photo (:class:`telegram.ChatPhoto`): Optional. Chat photo.
|
||||
Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
bio (:obj:`str`): Optional. Bio of the other party in a private chat. Returned only in
|
||||
:meth:`telegram.Bot.get_chat`.
|
||||
has_private_forwards (:obj:`bool`): Optional. :obj:`True`, if privacy settings of the other
|
||||
party in the private chat allows to use ``tg://user?id=<user_id>`` links only in chats
|
||||
with the user.
|
||||
with the user. Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
|
||||
.. versionadded:: 13.9
|
||||
description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats.
|
||||
Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
invite_link (:obj:`str`): Optional. Primary invite link, for groups, supergroups and
|
||||
channel. Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message
|
||||
|
|
@ -179,12 +186,13 @@ class Chat(TelegramObject):
|
|||
|
||||
.. versionadded:: 13.4
|
||||
has_protected_content (:obj:`bool`): Optional. :obj:`True`, if messages from the chat can't
|
||||
be forwarded to other chats.
|
||||
be forwarded to other chats. Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
|
||||
.. versionadded:: 13.9
|
||||
sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set.
|
||||
Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the
|
||||
sticker set.
|
||||
sticker set. Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
linked_chat_id (:obj:`int`): Optional. Unique identifier for the linked chat, i.e. the
|
||||
discussion group identifier for a channel and vice versa; for supergroups and channel
|
||||
chats. Returned only in :meth:`telegram.Bot.get_chat`.
|
||||
|
|
|
|||
|
|
@ -44,7 +44,8 @@ class ChatMember(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`user` and :attr:`status` are equal.
|
||||
|
||||
.. seealso:: `Chat Member Example <examples.chatmemberbot.html>`_
|
||||
Examples:
|
||||
:any:`Chat Member Bot <examples.chatmemberbot>`
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
|
|
|
|||
|
|
@ -44,6 +44,9 @@ class ChatMemberUpdated(TelegramObject):
|
|||
Note:
|
||||
In Python :keyword:`from` is a reserved word use :paramref:`from_user` instead.
|
||||
|
||||
Examples:
|
||||
:any:`Chat Member Bot <examples.chatmemberbot>`
|
||||
|
||||
Args:
|
||||
chat (:class:`telegram.Chat`): Chat the user belongs to.
|
||||
from_user (:class:`telegram.User`): Performer of the action, which resulted in the change.
|
||||
|
|
|
|||
|
|
@ -62,9 +62,11 @@ class InlineKeyboardButton(TelegramObject):
|
|||
|
||||
* After Bot API 6.1, only ``HTTPS`` links will be allowed in :paramref:`login_url`.
|
||||
|
||||
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
|
||||
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_,
|
||||
:class:`telegram.InlineKeyboardMarkup`
|
||||
Examples:
|
||||
* :any:`Inline Keyboard 1 <examples.inlinekeyboard>`
|
||||
* :any:`Inline Keyboard 2 <examples.inlinekeyboard2>`
|
||||
|
||||
.. seealso:: :class:`telegram.InlineKeyboardMarkup`
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
:attr:`web_app` is considered as well when comparing objects of this type in terms of
|
||||
|
|
@ -90,6 +92,9 @@ class InlineKeyboardButton(TelegramObject):
|
|||
Tip:
|
||||
The value entered here will be available in :attr:`telegram.CallbackQuery.data`.
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
|
||||
web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App
|
||||
<https://core.telegram.org/bots/webapps>`_ that will be launched when the user presses
|
||||
the button. The Web App will be able to send an arbitrary message on behalf of the user
|
||||
|
|
|
|||
|
|
@ -36,8 +36,9 @@ class InlineKeyboardMarkup(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their size of :attr:`inline_keyboard` and all the buttons are equal.
|
||||
|
||||
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
|
||||
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_
|
||||
Examples:
|
||||
* :any:`Inline Keyboard 1 <examples.inlinekeyboard>`
|
||||
* :any:`Inline Keyboard 2 <examples.inlinekeyboard2>`
|
||||
|
||||
Args:
|
||||
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
|
||||
|
|
|
|||
|
|
@ -33,6 +33,9 @@ class InlineQueryResult(TelegramObject):
|
|||
All URLs passed in inline query results will be available to end users and therefore must
|
||||
be assumed to be *public*.
|
||||
|
||||
Examples:
|
||||
:any:`Inline Bot <examples.inlinebot>`
|
||||
|
||||
Args:
|
||||
type (:obj:`str`): Type of the result.
|
||||
id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
|
||||
|
|
|
|||
|
|
@ -32,7 +32,8 @@ if TYPE_CHECKING:
|
|||
class InlineQueryResultArticle(InlineQueryResult):
|
||||
"""This object represents a Telegram InlineQueryResultArticle.
|
||||
|
||||
.. seealso:: `Inline Example <examples.inlinebot.html>`_
|
||||
Examples:
|
||||
:any:`Inline Bot <examples.inlinebot>`
|
||||
|
||||
Args:
|
||||
id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,8 @@ class InputTextMessageContent(InputMessageContent):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`message_text` is equal.
|
||||
|
||||
.. seealso:: `Inline Example <examples.inlinebot.html>`_
|
||||
Examples:
|
||||
:any:`Inline Bot <examples.inlinebot>`
|
||||
|
||||
Args:
|
||||
message_text (:obj:`str`): Text of the message to be sent,
|
||||
|
|
|
|||
|
|
@ -29,7 +29,8 @@ class KeyboardButtonPollType(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`type` is equal.
|
||||
|
||||
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
|
||||
Examples:
|
||||
:any:`Poll Bot <examples.pollbot>`
|
||||
|
||||
Attributes:
|
||||
type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@ class Message(TelegramObject):
|
|||
sent to channels. For backward compatibility, this will contain a fake sender user in
|
||||
non-channel chats, if the message was sent on behalf of a chat.
|
||||
sender_chat (:class:`telegram.Chat`, optional): Sender of the message, sent on behalf of a
|
||||
chat. For example, the channel itself for channel posts, the supergroup itself for
|
||||
chat. For example, the channel itself for channel posts, the supergroup itself for
|
||||
messages from anonymous group administrators, the linked channel for messages
|
||||
automatically forwarded to the discussion group. For backward compatibility,
|
||||
:attr:`from_user` contains a fake sender user in non-channel chats, if the message was
|
||||
|
|
@ -118,15 +118,17 @@ class Message(TelegramObject):
|
|||
or from anonymous administrators, information about the original sender chat.
|
||||
forward_from_message_id (:obj:`int`, optional): For forwarded channel posts, identifier of
|
||||
the original message in the channel.
|
||||
forward_sender_name (:obj:`str`, optional): Sender's name for messages forwarded from users
|
||||
who disallow adding a link to their account in forwarded messages.
|
||||
forward_sender_name (:obj:`str`, optional): Sender's name for messages forwarded from
|
||||
users who disallow adding a link to their account in forwarded messages.
|
||||
forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the
|
||||
original message was sent in Unix time. Converted to :class:`datetime.datetime`.
|
||||
is_automatic_forward (:obj:`bool`, optional): :obj:`True`, if the message is a channel post
|
||||
that was automatically forwarded to the connected discussion group.
|
||||
is_automatic_forward (:obj:`bool`, optional): :obj:`True`, if the message is a channel
|
||||
post that was automatically forwarded to the connected discussion group.
|
||||
|
||||
.. versionadded:: 13.9
|
||||
reply_to_message (:class:`telegram.Message`, optional): For replies, the original message.
|
||||
Note that the Message object in this field will not contain further
|
||||
``reply_to_message`` fields even if it itself is a reply.
|
||||
edit_date (:class:`datetime.datetime`, optional): Date the message was last edited in Unix
|
||||
time. Converted to :class:`datetime.datetime`.
|
||||
has_protected_content (:obj:`bool`, optional): :obj:`True`, if the message can't be
|
||||
|
|
@ -136,15 +138,16 @@ class Message(TelegramObject):
|
|||
media_group_id (:obj:`str`, optional): The unique identifier of a media message group this
|
||||
message belongs to.
|
||||
text (:obj:`str`, optional): For text messages, the actual UTF-8 text of the message,
|
||||
0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH`
|
||||
characters.
|
||||
0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters.
|
||||
entities (List[:class:`telegram.MessageEntity`], optional): For text messages, special
|
||||
entities like usernames, URLs, bot commands, etc. that appear in the text. See
|
||||
:attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly.
|
||||
This list is empty if the message does not contain entities.
|
||||
caption_entities (List[:class:`telegram.MessageEntity`], optional): For messages with a
|
||||
Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the
|
||||
caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities`
|
||||
methods for how to use properly.
|
||||
methods for how to use properly. This list is empty if the message does not contain
|
||||
caption entities.
|
||||
audio (:class:`telegram.Audio`, optional): Message is an audio file, information
|
||||
about the file.
|
||||
document (:class:`telegram.Document`, optional): Message is a general file, information
|
||||
|
|
@ -153,32 +156,33 @@ class Message(TelegramObject):
|
|||
about the animation. For backward compatibility, when this field is set, the document
|
||||
field will also be set.
|
||||
game (:class:`telegram.Game`, optional): Message is a game, information about the game.
|
||||
photo (List[:class:`telegram.PhotoSize`], optional): Message is a photo, available
|
||||
sizes of the photo.
|
||||
photo (List[:class:`telegram.PhotoSize`], optional): Message is a photo, available sizes
|
||||
of the photo. This list is empty if the message does not contain a photo.
|
||||
sticker (:class:`telegram.Sticker`, optional): Message is a sticker, information
|
||||
about the sticker.
|
||||
video (:class:`telegram.Video`, optional): Message is a video, information about the video.
|
||||
video (:class:`telegram.Video`, optional): Message is a video, information about the
|
||||
video.
|
||||
voice (:class:`telegram.Voice`, optional): Message is a voice message, information about
|
||||
the file.
|
||||
video_note (:class:`telegram.VideoNote`, optional): Message is a video note, information
|
||||
about the video message.
|
||||
new_chat_members (List[:class:`telegram.User`], optional): New members that were added to
|
||||
the group or supergroup and information about them (the bot itself may be one of these
|
||||
members).
|
||||
members). This list is empty if the message does not contain new chat members.
|
||||
caption (:obj:`str`, optional): Caption for the animation, audio, document, photo, video
|
||||
or voice, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters.
|
||||
contact (:class:`telegram.Contact`, optional): Message is a shared contact, information
|
||||
about the contact.
|
||||
location (:class:`telegram.Location`, optional): Message is a shared location, information
|
||||
about the location.
|
||||
venue (:class:`telegram.Venue`, optional): Message is a venue, information about the venue.
|
||||
For backward compatibility, when this field is set, the location field will also be
|
||||
set.
|
||||
venue (:class:`telegram.Venue`, optional): Message is a venue, information about the
|
||||
venue. For backward compatibility, when this field is set, the location field will
|
||||
also be set.
|
||||
left_chat_member (:class:`telegram.User`, optional): A member was removed from the group,
|
||||
information about them (this member may be the bot itself).
|
||||
new_chat_title (:obj:`str`, optional): A chat title was changed to this value.
|
||||
new_chat_photo (List[:class:`telegram.PhotoSize`], optional): A chat photo was changed to
|
||||
this value.
|
||||
this value. This list is empty if the message does not contain a new chat photo.
|
||||
delete_chat_photo (:obj:`bool`, optional): Service message: The chat photo was deleted.
|
||||
group_chat_created (:obj:`bool`, optional): Service message: The group has been created.
|
||||
supergroup_chat_created (:obj:`bool`, optional): Service message: The supergroup has been
|
||||
|
|
@ -194,19 +198,13 @@ class Message(TelegramObject):
|
|||
optional): Service message: auto-delete timer settings changed in the chat.
|
||||
|
||||
.. versionadded:: 13.4
|
||||
migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup with
|
||||
the specified identifier. This number may be greater than 32 bits and some programming
|
||||
languages may have difficulty/silent defects in interpreting it. But it is smaller than
|
||||
52 bits, so a signed 64 bit integer or double-precision float type are safe for storing
|
||||
this identifier.
|
||||
migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup
|
||||
with the specified identifier.
|
||||
migrate_from_chat_id (:obj:`int`, optional): The supergroup has been migrated from a group
|
||||
with the specified identifier. This number may be greater than 32 bits and some
|
||||
programming languages may have difficulty/silent defects in interpreting it. But it is
|
||||
smaller than 52 bits, so a signed 64 bit integer or double-precision float type are
|
||||
safe for storing this identifier.
|
||||
with the specified identifier.
|
||||
pinned_message (:class:`telegram.Message`, optional): Specified message was pinned. Note
|
||||
that the Message object in this field will not contain further :attr:`reply_to_message`
|
||||
fields even if it is itself a reply.
|
||||
that the Message object in this field will not contain further
|
||||
:attr:`reply_to_message` fields even if it is itself a reply.
|
||||
invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment,
|
||||
information about the invoice.
|
||||
successful_payment (:class:`telegram.SuccessfulPayment`, optional): Message is a service
|
||||
|
|
@ -215,13 +213,15 @@ class Message(TelegramObject):
|
|||
has logged in.
|
||||
forward_signature (:obj:`str`, optional): For messages forwarded from channels, signature
|
||||
of the post author if present.
|
||||
author_signature (:obj:`str`, optional): Signature of the post author for messages in
|
||||
author_signature (:obj:`str`, optional): Signature of the post author for messages in
|
||||
channels, or the custom title of an anonymous group administrator.
|
||||
forward_sender_name (:obj:`str`, optional): Sender's name for messages forwarded from
|
||||
users who disallow adding a link to their account in forwarded messages.
|
||||
passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data.
|
||||
poll (:class:`telegram.Poll`, optional): Message is a native poll,
|
||||
information about the poll.
|
||||
dice (:class:`telegram.Dice`, optional): Message is a dice with random value from 1 to 6.
|
||||
via_bot (:class:`telegram.User`, optional): Message was sent through an inline bot.
|
||||
dice (:class:`telegram.Dice`, optional): Message is a dice with random value.
|
||||
via_bot (:class:`telegram.User`, optional): Bot through which message was sent.
|
||||
proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`, optional): Service
|
||||
message. A user in the chat triggered another user's proximity alert while sharing
|
||||
Live Location.
|
||||
|
|
@ -246,7 +246,8 @@ class Message(TelegramObject):
|
|||
|
||||
.. versionadded:: 20.0
|
||||
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
|
||||
to the message. ``login_url`` buttons are represented as ordinary url buttons.
|
||||
to the message. :paramref:`~telegram.InlineKeyboardButton.login_url` buttons are
|
||||
represented as ordinary url buttons.
|
||||
|
||||
Attributes:
|
||||
message_id (:obj:`int`): Unique message identifier inside this chat.
|
||||
|
|
@ -254,94 +255,125 @@ class Message(TelegramObject):
|
|||
sent to channels. For backward compatibility, this will contain a fake sender user in
|
||||
non-channel chats, if the message was sent on behalf of a chat.
|
||||
sender_chat (:class:`telegram.Chat`): Optional. Sender of the message, sent on behalf of a
|
||||
chat. For backward compatibility, :attr:`from_user` contains a fake sender user in
|
||||
non-channel chats, if the message was sent on behalf of a chat.
|
||||
date (:class:`datetime.datetime`): Date the message was sent.
|
||||
chat. For example, the channel itself for channel posts, the supergroup itself for
|
||||
messages from anonymous group administrators, the linked channel for messages
|
||||
automatically forwarded to the discussion group. For backward compatibility,
|
||||
:attr:`from_user` contains a fake sender user in non-channel chats, if the message was
|
||||
sent on behalf of a chat.
|
||||
date (:class:`datetime.datetime`): Date the message was sent in Unix time. Converted to
|
||||
:class:`datetime.datetime`.
|
||||
chat (:class:`telegram.Chat`): Conversation the message belongs to.
|
||||
forward_from (:class:`telegram.User`): Optional. Sender of the original message.
|
||||
forward_from (:class:`telegram.User`): Optional. For forwarded messages, sender of the
|
||||
original message.
|
||||
forward_from_chat (:class:`telegram.Chat`): Optional. For messages forwarded from channels
|
||||
or from anonymous administrators, information about the original sender chat.
|
||||
forward_from_message_id (:obj:`int`): Optional. Identifier of the original message in the
|
||||
channel.
|
||||
forward_date (:class:`datetime.datetime`): Optional. Date the original message was sent.
|
||||
is_automatic_forward (:obj:`bool`): Optional. :obj:`True`, if the message is a channel post
|
||||
that was automatically forwarded to the connected discussion group.
|
||||
forward_from_message_id (:obj:`int`): Optional. For forwarded channel posts, identifier of
|
||||
the original message in the channel.
|
||||
forward_date (:class:`datetime.datetime`): Optional. For forwarded messages, date the
|
||||
original message was sent in Unix time. Converted to :class:`datetime.datetime`.
|
||||
is_automatic_forward (:obj:`bool`): Optional. :obj:`True`, if the message is a channel
|
||||
post that was automatically forwarded to the connected discussion group.
|
||||
|
||||
.. versionadded:: 13.9
|
||||
reply_to_message (:class:`telegram.Message`): Optional. For replies, the original message.
|
||||
Note that the Message object in this field will not contain further
|
||||
``reply_to_message`` fields even if it itself is a reply.
|
||||
edit_date (:class:`datetime.datetime`): Optional. Date the message was last edited.
|
||||
edit_date (:class:`datetime.datetime`): Optional. Date the message was last edited in Unix
|
||||
time. Converted to :class:`datetime.datetime`.
|
||||
has_protected_content (:obj:`bool`): Optional. :obj:`True`, if the message can't be
|
||||
forwarded.
|
||||
|
||||
.. versionadded:: 13.9
|
||||
media_group_id (:obj:`str`): Optional. The unique identifier of a media message group this
|
||||
message belongs to.
|
||||
text (:obj:`str`): Optional. The actual UTF-8 text of the message.
|
||||
entities (List[:class:`telegram.MessageEntity`]): Special entities like
|
||||
usernames, URLs, bot commands, etc. that appear in the text. See
|
||||
:attr:`Message.parse_entity` and :attr:`parse_entities` methods for how to use
|
||||
properly. This list is empty if the message does not contain entities.
|
||||
caption_entities (List[:class:`telegram.MessageEntity`]): Special entities like
|
||||
usernames, URLs, bot commands, etc. that appear in the caption. See
|
||||
:attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities` methods for how
|
||||
to use properly. This list is empty if the message does not contain caption entities.
|
||||
audio (:class:`telegram.Audio`): Optional. Information about the file.
|
||||
document (:class:`telegram.Document`): Optional. Information about the file.
|
||||
animation (:class:`telegram.Animation`) Optional. Information about the file.
|
||||
For backward compatibility, when this field is set, the document field will also be
|
||||
set.
|
||||
game (:class:`telegram.Game`): Optional. Information about the game.
|
||||
photo (List[:class:`telegram.PhotoSize`]): Available sizes of the photo.
|
||||
This list is empty if the message does not contain a photo.
|
||||
sticker (:class:`telegram.Sticker`): Optional. Information about the sticker.
|
||||
video (:class:`telegram.Video`): Optional. Information about the video.
|
||||
voice (:class:`telegram.Voice`): Optional. Information about the file.
|
||||
video_note (:class:`telegram.VideoNote`): Optional. Information about the video message.
|
||||
new_chat_members (List[:class:`telegram.User`]): Information about new members to
|
||||
the chat. The bot itself may be one of these members.
|
||||
This list is empty if the message does not contain new chat members.
|
||||
caption (:obj:`str`): Optional. Caption for the document, photo or video,
|
||||
0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH`
|
||||
characters.
|
||||
contact (:class:`telegram.Contact`): Optional. Information about the contact.
|
||||
location (:class:`telegram.Location`): Optional. Information about the location.
|
||||
venue (:class:`telegram.Venue`): Optional. Information about the venue.
|
||||
left_chat_member (:class:`telegram.User`): Optional. Information about the user that left
|
||||
the group. (this member may be the bot itself).
|
||||
text (:obj:`str`): Optional. For text messages, the actual UTF-8 text of the message,
|
||||
0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters.
|
||||
entities (List[:class:`telegram.MessageEntity`]): Optional. For text messages, special
|
||||
entities like usernames, URLs, bot commands, etc. that appear in the text. See
|
||||
:attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly.
|
||||
This list is empty if the message does not contain entities.
|
||||
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. For messages with a
|
||||
Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the
|
||||
caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities`
|
||||
methods for how to use properly. This list is empty if the message does not contain
|
||||
caption entities.
|
||||
audio (:class:`telegram.Audio`): Optional. Message is an audio file, information
|
||||
about the file.
|
||||
document (:class:`telegram.Document`): Optional. Message is a general file, information
|
||||
about the file.
|
||||
animation (:class:`telegram.Animation`): Optional. Message is an animation, information
|
||||
about the animation. For backward compatibility, when this field is set, the document
|
||||
field will also be set.
|
||||
game (:class:`telegram.Game`): Optional. Message is a game, information about the game.
|
||||
photo (List[:class:`telegram.PhotoSize`]): Optional. Message is a photo, available sizes
|
||||
of the photo. This list is empty if the message does not contain a photo.
|
||||
sticker (:class:`telegram.Sticker`): Optional. Message is a sticker, information
|
||||
about the sticker.
|
||||
video (:class:`telegram.Video`): Optional. Message is a video, information about the
|
||||
video.
|
||||
voice (:class:`telegram.Voice`): Optional. Message is a voice message, information about
|
||||
the file.
|
||||
video_note (:class:`telegram.VideoNote`): Optional. Message is a video note, information
|
||||
about the video message.
|
||||
new_chat_members (List[:class:`telegram.User`]): Optional. New members that were added to
|
||||
the group or supergroup and information about them (the bot itself may be one of these
|
||||
members). This list is empty if the message does not contain new chat members.
|
||||
caption (:obj:`str`): Optional. Caption for the animation, audio, document, photo, video
|
||||
or voice, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters.
|
||||
contact (:class:`telegram.Contact`): Optional. Message is a shared contact, information
|
||||
about the contact.
|
||||
location (:class:`telegram.Location`): Optional. Message is a shared location, information
|
||||
about the location.
|
||||
venue (:class:`telegram.Venue`): Optional. Message is a venue, information about the
|
||||
venue. For backward compatibility, when this field is set, the location field will
|
||||
also be set.
|
||||
left_chat_member (:class:`telegram.User`): Optional. A member was removed from the group,
|
||||
information about them (this member may be the bot itself).
|
||||
new_chat_title (:obj:`str`): Optional. A chat title was changed to this value.
|
||||
new_chat_photo (List[:class:`telegram.PhotoSize`]): A chat photo was changed to
|
||||
this value. This list is empty if the message does not contain a new chat photo.
|
||||
delete_chat_photo (:obj:`bool`): Optional. The chat photo was deleted.
|
||||
group_chat_created (:obj:`bool`): Optional. The group has been created.
|
||||
supergroup_chat_created (:obj:`bool`): Optional. The supergroup has been created.
|
||||
channel_chat_created (:obj:`bool`): Optional. The channel has been created.
|
||||
delete_chat_photo (:obj:`bool`): Optional. Service message: The chat photo was deleted.
|
||||
group_chat_created (:obj:`bool`): Optional. Service message: The group has been created.
|
||||
supergroup_chat_created (:obj:`bool`): Optional. Service message: The supergroup has been
|
||||
created. This field can't be received in a message coming through updates, because bot
|
||||
can't be a member of a supergroup when it is created. It can only be found in
|
||||
:attr:`reply_to_message` if someone replies to a very first message in a directly
|
||||
created supergroup.
|
||||
channel_chat_created (:obj:`bool`): Optional. Service message: The channel has been
|
||||
created. This field can't be received in a message coming through updates, because bot
|
||||
can't be a member of a channel when it is created. It can only be found in
|
||||
:attr:`reply_to_message` if someone replies to a very first message in a channel.
|
||||
message_auto_delete_timer_changed (:class:`telegram.MessageAutoDeleteTimerChanged`):
|
||||
Optional. Service message: auto-delete timer settings changed in the chat.
|
||||
|
||||
.. versionadded:: 13.4
|
||||
migrate_to_chat_id (:obj:`int`): Optional. The group has been migrated to a supergroup with
|
||||
the specified identifier.
|
||||
migrate_to_chat_id (:obj:`int`): Optional. The group has been migrated to a supergroup
|
||||
with the specified identifier.
|
||||
migrate_from_chat_id (:obj:`int`): Optional. The supergroup has been migrated from a group
|
||||
with the specified identifier.
|
||||
pinned_message (:class:`telegram.Message`): Optional. Specified message was pinned.
|
||||
invoice (:class:`telegram.Invoice`): Optional. Information about the invoice.
|
||||
successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Information about the
|
||||
payment.
|
||||
pinned_message (:class:`telegram.Message`): Optional. Specified message was pinned. Note
|
||||
that the Message object in this field will not contain further
|
||||
:attr:`reply_to_message` fields even if it is itself a reply.
|
||||
invoice (:class:`telegram.Invoice`): Optional. Message is an invoice for a payment,
|
||||
information about the invoice.
|
||||
successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Message is a service
|
||||
message about a successful payment, information about the payment.
|
||||
connected_website (:obj:`str`): Optional. The domain name of the website on which the user
|
||||
has logged in.
|
||||
forward_signature (:obj:`str`): Optional. Signature of the post author for messages
|
||||
forwarded from channels.
|
||||
forward_sender_name (:obj:`str`): Optional. Sender's name for messages forwarded from users
|
||||
who disallow adding a link to their account in forwarded messages.
|
||||
forward_signature (:obj:`str`): Optional. For messages forwarded from channels, signature
|
||||
of the post author if present.
|
||||
author_signature (:obj:`str`): Optional. Signature of the post author for messages in
|
||||
channels, or the custom title of an anonymous group administrator.
|
||||
forward_sender_name (:obj:`str`): Optional. Sender's name for messages forwarded from
|
||||
users who disallow adding a link to their account in forwarded messages.
|
||||
passport_data (:class:`telegram.PassportData`): Optional. Telegram Passport data.
|
||||
|
||||
Examples:
|
||||
:any:`Passport Bot <examples.passportbot>`
|
||||
poll (:class:`telegram.Poll`): Optional. Message is a native poll,
|
||||
information about the poll.
|
||||
dice (:class:`telegram.Dice`): Optional. Message is a dice.
|
||||
via_bot (:class:`telegram.User`): Optional. Bot through which the message was sent.
|
||||
dice (:class:`telegram.Dice`): Optional. Message is a dice with random value.
|
||||
via_bot (:class:`telegram.User`): Optional. Bot through which message was sent.
|
||||
proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`): Optional. Service
|
||||
message. A user in the chat triggered another user's proximity alert while sharing
|
||||
Live Location.
|
||||
|
|
@ -366,7 +398,8 @@ class Message(TelegramObject):
|
|||
|
||||
.. versionadded:: 20.0
|
||||
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
|
||||
to the message.
|
||||
to the message. :paramref:`~telegram.InlineKeyboardButton.login_url` buttons are
|
||||
represented as ordinary url buttons.
|
||||
|
||||
.. |custom_emoji_formatting_note| replace:: Custom emoji entities will currently be ignored
|
||||
by this function. Instead, the supplied replacement for the emoji will be used.
|
||||
|
|
@ -700,7 +733,7 @@ class Message(TelegramObject):
|
|||
* :class:`telegram.VideoNote`
|
||||
* :class:`telegram.Voice`
|
||||
|
||||
Otherwise :obj:`None` is returned.
|
||||
Otherwise :obj:`None` is returned.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
:attr:`dice`, :attr:`passport_data` and :attr:`poll` are now also considered to be an
|
||||
|
|
@ -3086,10 +3119,11 @@ class Message(TelegramObject):
|
|||
in the same way the original message was formatted.
|
||||
|
||||
Note:
|
||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use :meth:`text_markdown_v2` instead.
|
||||
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use
|
||||
:meth:`text_markdown_v2` instead.
|
||||
|
||||
|custom_emoji_formatting_note|
|
||||
* |custom_emoji_formatting_note|
|
||||
|
||||
Returns:
|
||||
:obj:`str`: Message text with entities formatted as Markdown.
|
||||
|
|
@ -3129,11 +3163,11 @@ class Message(TelegramObject):
|
|||
This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink.
|
||||
|
||||
Note:
|
||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use :meth:`text_markdown_v2_urled`
|
||||
instead.
|
||||
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use :meth:`text_markdown_v2_urled`
|
||||
instead.
|
||||
|
||||
|custom_emoji_formatting_note|
|
||||
* |custom_emoji_formatting_note|
|
||||
|
||||
Returns:
|
||||
:obj:`str`: Message text with entities formatted as Markdown.
|
||||
|
|
@ -3173,11 +3207,11 @@ class Message(TelegramObject):
|
|||
Markdown in the same way the original message was formatted.
|
||||
|
||||
Note:
|
||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use :meth:`caption_markdown_v2`
|
||||
instead.
|
||||
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use :meth:`caption_markdown_v2`
|
||||
instead.
|
||||
|
||||
|custom_emoji_formatting_note|
|
||||
* |custom_emoji_formatting_note|
|
||||
|
||||
Returns:
|
||||
:obj:`str`: Message caption with caption entities formatted as Markdown.
|
||||
|
|
@ -3219,11 +3253,11 @@ class Message(TelegramObject):
|
|||
Markdown. This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink.
|
||||
|
||||
Note:
|
||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use :meth:`caption_markdown_v2_urled`
|
||||
instead.
|
||||
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||
Telegram for backward compatibility. You should use
|
||||
:meth:`caption_markdown_v2_urled` instead.
|
||||
|
||||
|custom_emoji_formatting_note|
|
||||
* |custom_emoji_formatting_note|
|
||||
|
||||
Returns:
|
||||
:obj:`str`: Message caption with caption entities formatted as Markdown.
|
||||
|
|
|
|||
|
|
@ -63,13 +63,26 @@ class MessageEntity(TelegramObject):
|
|||
|
||||
.. versionadded:: 20.0
|
||||
Attributes:
|
||||
type (:obj:`str`): Type of the entity.
|
||||
type (:obj:`str`): Type of the entity. Can be :attr:`MENTION` (@username),
|
||||
:attr:`HASHTAG`, :attr:`BOT_COMMAND`,
|
||||
:attr:`URL`, :attr:`EMAIL`, :attr:`PHONE_NUMBER`, :attr:`BOLD` (bold text),
|
||||
:attr:`ITALIC` (italic text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
|
||||
:attr:`CODE` (monowidth string), :attr:`PRE` (monowidth block), :attr:`TEXT_LINK` (for
|
||||
clickable text URLs), :attr:`TEXT_MENTION` (for users without usernames),
|
||||
:attr:`CUSTOM_EMOJI` (for inline custom emoji stickers).
|
||||
|
||||
.. versionadded:: 20.0
|
||||
Added inline custom emoji
|
||||
offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity.
|
||||
length (:obj:`int`): Length of the entity in UTF-16 code units.
|
||||
url (:obj:`str`): Optional. Url that will be opened after user taps on the text.
|
||||
url (:obj:`str`): Optional. For :attr:`TEXT_LINK` only, url that will be opened after
|
||||
user taps on the text.
|
||||
user (:class:`telegram.User`): Optional. The mentioned user.
|
||||
language (:obj:`str`): Optional. Programming language of the entity text.
|
||||
custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji.
|
||||
language (:obj:`str`): Optional. For :attr:`PRE` only, The programming language of
|
||||
the entity text.
|
||||
custom_emoji_id (:obj:`str`): Optional. For :attr:`CUSTOM_EMOJI` only, unique identifier
|
||||
of the custom emoji. Use :meth:`telegram.Bot.get_custom_emoji_stickers` to get full
|
||||
information about the sticker.
|
||||
|
||||
.. versionadded:: 20.0
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,8 @@ class LabeledPrice(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`label` and :attr:`amount` are equal.
|
||||
|
||||
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
|
||||
Examples:
|
||||
:any:`Payment Bot <examples.paymentbot>`
|
||||
|
||||
Args:
|
||||
label (:obj:`str`): Portion label.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,8 @@ class ShippingOption(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`id` is equal.
|
||||
|
||||
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
|
||||
Examples:
|
||||
:any:`Payment Bot <examples.paymentbot>`
|
||||
|
||||
Args:
|
||||
id (:obj:`str`): Shipping option identifier.
|
||||
|
|
|
|||
|
|
@ -116,7 +116,8 @@ class Poll(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`id` is equal.
|
||||
|
||||
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
|
||||
Examples:
|
||||
:any:`Poll Bot <examples.pollbot>`
|
||||
|
||||
Args:
|
||||
id (:obj:`str`): Unique poll identifier.
|
||||
|
|
@ -126,13 +127,17 @@ class Poll(TelegramObject):
|
|||
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
|
||||
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
|
||||
allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers.
|
||||
correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer option.
|
||||
Available only for polls in the quiz mode, which are closed, or was sent (not
|
||||
forwarded) by the bot or to the private chat with the bot.
|
||||
correct_option_id (:obj:`int`, optional): A zero based identifier of the correct answer
|
||||
option. Available only for closed polls in the quiz mode, which were sent
|
||||
(not forwarded), by the bot or to a private chat with the bot.
|
||||
explanation (:obj:`str`, optional): Text that is shown when a user chooses an incorrect
|
||||
answer or taps on the lamp icon in a quiz-style poll, 0-200 characters.
|
||||
explanation_entities (List[:class:`telegram.MessageEntity`], optional): Special entities
|
||||
like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
|
||||
This list is empty if the message does not contain explanation entities.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
This attribute is now always a (possibly empty) list and never :obj:`None`.
|
||||
open_period (:obj:`int`, optional): Amount of time in seconds the poll will be active
|
||||
after creation.
|
||||
close_date (:obj:`datetime.datetime`, optional): Point in time (Unix timestamp) when the
|
||||
|
|
@ -147,9 +152,11 @@ class Poll(TelegramObject):
|
|||
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
|
||||
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
|
||||
allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers.
|
||||
correct_option_id (:obj:`int`): Optional. Identifier of the correct answer option.
|
||||
correct_option_id (:obj:`int`, optional): A zero based identifier of the correct answer
|
||||
option. Available only for closed polls in the quiz mode, which were sent
|
||||
(not forwarded), by the bot or to a private chat with the bot.
|
||||
explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect
|
||||
answer or taps on the lamp icon in a quiz-style poll.
|
||||
answer or taps on the lamp icon in a quiz-style poll, 0-200 characters.
|
||||
explanation_entities (List[:class:`telegram.MessageEntity`]): Special entities
|
||||
like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
|
||||
This list is empty if the message does not contain explanation entities.
|
||||
|
|
|
|||
|
|
@ -32,9 +32,12 @@ class ReplyKeyboardMarkup(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their size of :attr:`keyboard` and all the buttons are equal.
|
||||
|
||||
Example:
|
||||
A user requests to change the bot's language, bot replies to the request with a keyboard
|
||||
to select the new language. Other users in the group don't see the keyboard.
|
||||
Examples:
|
||||
* Example usage: A user requests to change the bot's language, bot replies to the request
|
||||
with a keyboard to select the new language. Other users in the group don't see
|
||||
the keyboard.
|
||||
* :any:`Conversation Bot <examples.conversationbot>`
|
||||
* :any:`Conversation Bot 2 <examples.conversationbot2>`
|
||||
|
||||
Args:
|
||||
keyboard (List[List[:obj:`str` | :class:`telegram.KeyboardButton`]]): Array of button rows,
|
||||
|
|
|
|||
|
|
@ -29,15 +29,17 @@ class ReplyKeyboardRemove(TelegramObject):
|
|||
until a new keyboard is sent by a bot. An exception is made for one-time keyboards that are
|
||||
hidden immediately after the user presses a button (see :class:`telegram.ReplyKeyboardMarkup`).
|
||||
|
||||
Example:
|
||||
A user votes in a poll, bot returns confirmation message in reply to the vote and removes
|
||||
the keyboard for that user, while still showing the keyboard with poll options to users who
|
||||
haven't voted yet.
|
||||
|
||||
Note:
|
||||
User will not be able to summon this keyboard; if you want to hide the keyboard from
|
||||
sight but keep it accessible, use :attr:`telegram.ReplyKeyboardMarkup.one_time_keyboard`.
|
||||
|
||||
Examples:
|
||||
* Example usage: A user votes in a poll, bot returns confirmation message in reply to
|
||||
the vote and removes the keyboard for that user, while still showing the keyboard with
|
||||
poll options to users who haven't voted yet.
|
||||
* :any:`Conversation Bot <examples.conversationbot>`
|
||||
* :any:`Conversation Bot 2 <examples.conversationbot2>`
|
||||
|
||||
Args:
|
||||
selective (:obj:`bool`, optional): Use this parameter if you want to remove the keyboard
|
||||
for specific users only. Targets:
|
||||
|
|
|
|||
|
|
@ -37,20 +37,12 @@ Tele_co = TypeVar("Tele_co", bound="TelegramObject", covariant=True)
|
|||
class TelegramObject:
|
||||
"""Base class for most Telegram objects.
|
||||
|
||||
Objects of this type are subscriptable with strings, where ``telegram_object[attribute_name]``
|
||||
is equivalent to ``telegram_object.attribute_name``. If the object does not have an attribute
|
||||
with the appropriate name, a :exc:`KeyError` will be raised.
|
||||
|
||||
When objects of this type are pickled, the :class:`~telegram.Bot` attribute associated with the
|
||||
object will be removed. However, when copying the object via :func:`copy.deepcopy`, the copy
|
||||
will have the *same* bot instance associated with it, i.e::
|
||||
|
||||
assert telegram_object.get_bot() is copy.deepcopy(telegram_object).get_bot()
|
||||
Objects of this type are subscriptable with strings. See :meth:`__getitem__` for more details.
|
||||
The :mod:`pickle` and :func:`~copy.deepcopy` behavior of objects of this type are defined by
|
||||
:meth:`__getstate__`, :meth:`__setstate__` and :meth:`__deepcopy__`.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* ``telegram_object['from']`` will look up the key ``from_user``. This is to account for
|
||||
special cases like :attr:`Message.from_user` that deviate from the official Bot API.
|
||||
* Removed argument and attribute ``bot`` for several subclasses. Use
|
||||
:meth:`set_bot` and :meth:`get_bot` instead.
|
||||
* Removed the possibility to pass arbitrary keyword arguments for several subclasses.
|
||||
|
|
@ -108,7 +100,7 @@ class TelegramObject:
|
|||
def __repr__(self) -> str:
|
||||
"""Gives a string representation of this object in the form
|
||||
``ClassName(attr_1=value_1, attr_2=value_2, ...)``, where attributes are omitted if they
|
||||
have the value :obj:`None` or empty instances of :class:`collections.abc.Sized` (e.g.
|
||||
have the value :obj:`None` or are empty instances of :class:`collections.abc.Sized` (e.g.
|
||||
:class:`list`, :class:`dict`, :class:`set`, :class:`str`, etc.).
|
||||
|
||||
As this class doesn't implement :meth:`object.__str__`, the default implementation
|
||||
|
|
@ -141,6 +133,30 @@ class TelegramObject:
|
|||
return f"{self.__class__.__name__}({contents})"
|
||||
|
||||
def __getitem__(self, item: str) -> object:
|
||||
"""
|
||||
Objects of this type are subscriptable with strings, where
|
||||
``telegram_object["attribute_name"]`` is equivalent to ``telegram_object.attribute_name``.
|
||||
|
||||
Tip:
|
||||
This is useful for dynamic attribute lookup, i.e. ``telegram_object[arg]`` where the
|
||||
value of ``arg`` is determined at runtime.
|
||||
In all other cases, it's recommended to use the dot notation instead, i.e.
|
||||
``telegram_object.attribute_name``.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
``telegram_object['from']`` will look up the key ``from_user``. This is to account for
|
||||
special cases like :attr:`Message.from_user` that deviate from the official Bot API.
|
||||
|
||||
Args:
|
||||
item (:obj:`str`): The name of the attribute to look up.
|
||||
|
||||
Returns:
|
||||
:obj:`object`
|
||||
|
||||
Raises:
|
||||
:exc:`KeyError`: If the object does not have an attribute with the appropriate name.
|
||||
"""
|
||||
if item == "from":
|
||||
item = "from_user"
|
||||
try:
|
||||
|
|
@ -153,15 +169,28 @@ class TelegramObject:
|
|||
|
||||
def __getstate__(self) -> Dict[str, Union[str, object]]:
|
||||
"""
|
||||
This method is used for pickling. We remove the bot attribute of the object since those
|
||||
are not pickable.
|
||||
Overrides :meth:`object.__getstate__` to customize the pickling process of objects of this
|
||||
type.
|
||||
The returned state does `not` contain the :class:`telegram.Bot` instance set with
|
||||
:meth:`set_bot` (if any), as it can't be pickled.
|
||||
|
||||
Returns:
|
||||
state (Dict[:obj:`str`, :obj:`object`]): The state of the object.
|
||||
"""
|
||||
return self._get_attrs(include_private=True, recursive=False, remove_bot=True)
|
||||
|
||||
def __setstate__(self, state: dict) -> None:
|
||||
"""
|
||||
This method is used for unpickling. The data, which is in the form a dictionary, is
|
||||
converted back into a class. Should be modified in place.
|
||||
Overrides :meth:`object.__setstate__` to customize the unpickling process of objects of
|
||||
this type. Modifies the object in-place.
|
||||
If any data was stored in the :attr:`api_kwargs` of the pickled object, this method checks
|
||||
if the class now has dedicated attributes for those keys and moves the values from
|
||||
:attr:`api_kwargs` to the dedicated attributes.
|
||||
This can happen, if serialized data is loaded with a new version of this library, where
|
||||
the new version was updated to account for updates of the Telegram Bot API.
|
||||
|
||||
Args:
|
||||
state (:obj:`dict`): The data to set as attributes of this object.
|
||||
"""
|
||||
# Make sure that we have a `_bot` attribute. This is necessary, since __getstate__ omits
|
||||
# this as Bots are not pickable.
|
||||
|
|
@ -172,7 +201,20 @@ class TelegramObject:
|
|||
self._apply_api_kwargs()
|
||||
|
||||
def __deepcopy__(self: Tele_co, memodict: dict) -> Tele_co:
|
||||
"""This method deepcopies the object and sets the bot on the newly created copy."""
|
||||
"""
|
||||
Customizes how :func:`copy.deepcopy` processes objects of this type.
|
||||
The only difference to the default implementation is that the :class:`telegram.Bot`
|
||||
instance set via :meth:`set_bot` (if any) is not copied, but shared between the original
|
||||
and the copy, i.e.::
|
||||
|
||||
assert telegram_object.get_bot() is copy.deepcopy(telegram_object).get_bot()
|
||||
|
||||
Args:
|
||||
memodict (:obj:`dict`): A dictionary that maps objects to their copies.
|
||||
|
||||
Returns:
|
||||
:obj:`telegram.TelegramObject`: The copied object.
|
||||
"""
|
||||
bot = self._bot # Save bot so we can set it after copying
|
||||
self.set_bot(None) # set to None so it is not deepcopied
|
||||
cls = self.__class__
|
||||
|
|
@ -387,6 +429,26 @@ class TelegramObject:
|
|||
self._bot = bot
|
||||
|
||||
def __eq__(self, other: object) -> bool:
|
||||
"""Compares this object with :paramref:`other` in terms of equality.
|
||||
If this object and :paramref:`other` are `not` objects of the same class,
|
||||
this comparison will fall back to Python's default implementation of :meth:`object.__eq__`.
|
||||
Otherwise, both objects may be compared in terms of equality, if the corresponding
|
||||
subclass of :class:`TelegramObject` has defined a set of attributes to compare and
|
||||
the objects are considered to be equal, if all of these attributes are equal.
|
||||
If the subclass has not defined a set of attributes to compare, a warning will be issued.
|
||||
|
||||
Tip:
|
||||
If instances of a class in the :mod:`telegram` module are comparable in terms of
|
||||
equality, the documentation of the class will state the attributes that will be used
|
||||
for this comparison.
|
||||
|
||||
Args:
|
||||
other (:obj:`object`): The object to compare with.
|
||||
|
||||
Returns:
|
||||
:obj:`bool`
|
||||
|
||||
"""
|
||||
if isinstance(other, self.__class__):
|
||||
if not self._id_attrs:
|
||||
warn(
|
||||
|
|
@ -404,6 +466,12 @@ class TelegramObject:
|
|||
return super().__eq__(other)
|
||||
|
||||
def __hash__(self) -> int:
|
||||
"""Builds a hash value for this object such that the hash of two objects is equal if and
|
||||
only if the objects are equal in terms of :meth:`__eq__`.
|
||||
|
||||
Returns:
|
||||
:obj:`int`
|
||||
"""
|
||||
if self._id_attrs:
|
||||
return hash((self.__class__, self._id_attrs))
|
||||
return super().__hash__()
|
||||
|
|
|
|||
|
|
@ -46,6 +46,9 @@ class Update(TelegramObject):
|
|||
Note:
|
||||
At most one of the optional parameters can be present in any given update.
|
||||
|
||||
.. seealso:: `Your First Bot <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Your-first-Bot>`_
|
||||
|
||||
Args:
|
||||
update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a
|
||||
certain positive number and increase sequentially. This ID becomes especially handy if
|
||||
|
|
@ -104,6 +107,9 @@ class Update(TelegramObject):
|
|||
chosen_inline_result (:class:`telegram.ChosenInlineResult`): Optional. The result of an
|
||||
inline query that was chosen by a user.
|
||||
callback_query (:class:`telegram.CallbackQuery`): Optional. New incoming callback query.
|
||||
|
||||
Examples:
|
||||
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||
shipping_query (:class:`telegram.ShippingQuery`): Optional. New incoming shipping query.
|
||||
pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming
|
||||
pre-checkout query.
|
||||
|
|
|
|||
|
|
@ -28,7 +28,8 @@ class WebAppData(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`data` and :attr:`button_text` are equal.
|
||||
|
||||
.. seealso:: `Webappbot Example <examples.webappbot.html>`_
|
||||
Examples:
|
||||
:any:`Webapp Bot <examples.webappbot>`
|
||||
|
||||
.. versionadded:: 20.0
|
||||
|
||||
|
|
@ -45,8 +46,7 @@ class WebAppData(TelegramObject):
|
|||
button, from which the Web App was opened.
|
||||
|
||||
Warning:
|
||||
Be aware that a bad client can send
|
||||
arbitrary data in this field.
|
||||
Be aware that a bad client can send arbitrary data in this field.
|
||||
"""
|
||||
|
||||
__slots__ = ("data", "button_text")
|
||||
|
|
|
|||
|
|
@ -29,7 +29,8 @@ class WebAppInfo(TelegramObject):
|
|||
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||
considered equal, if their :attr:`url` are equal.
|
||||
|
||||
.. seealso:: `Webappbot Example <examples.webappbot.html>`_
|
||||
Examples:
|
||||
:any:`Webapp Bot <examples.webappbot>`
|
||||
|
||||
.. versionadded:: 20.0
|
||||
|
||||
|
|
|
|||
|
|
@ -62,14 +62,17 @@ class WebhookInfo(TelegramObject):
|
|||
|
||||
.. versionadded:: 20.0
|
||||
Attributes:
|
||||
url (:obj:`str`): Webhook URL.
|
||||
has_custom_certificate (:obj:`bool`): If a custom certificate was provided for webhook.
|
||||
url (:obj:`str`): Webhook URL, may be empty if webhook is not set up.
|
||||
has_custom_certificate (:obj:`bool`): :obj:`True`, if a custom certificate was provided for
|
||||
webhook certificate checks.
|
||||
pending_update_count (:obj:`int`): Number of updates awaiting delivery.
|
||||
ip_address (:obj:`str`): Optional. Currently used webhook IP address.
|
||||
last_error_date (:obj:`int`): Optional. Unix time for the most recent error that happened.
|
||||
last_error_message (:obj:`str`): Optional. Error message in human-readable format.
|
||||
last_error_date (:obj:`int`): Optional. Unix time for the most recent error that happened
|
||||
when trying to deliver an update via webhook.
|
||||
last_error_message (:obj:`str`): Optional. Error message in human-readable format for the
|
||||
most recent error that happened when trying to deliver an update via webhook.
|
||||
max_connections (:obj:`int`): Optional. Maximum allowed number of simultaneous HTTPS
|
||||
connections.
|
||||
connections to the webhook for update delivery.
|
||||
allowed_updates (List[:obj:`str`]): Optional. A list of update types the bot is subscribed
|
||||
to. Defaults to all update types, except :attr:`telegram.Update.chat_member`.
|
||||
last_synchronization_error_date (:obj:`int`): Optional. Unix time of the most recent error
|
||||
|
|
|
|||
|
|
@ -56,7 +56,12 @@ def _lstrip_str(in_s: str, lstr: str) -> str:
|
|||
|
||||
|
||||
class TelegramError(Exception):
|
||||
"""Base class for Telegram errors."""
|
||||
"""
|
||||
Base class for Telegram errors.
|
||||
|
||||
.. seealso:: `Exceptions, Warnings and Logging <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Exceptions%2C-Warnings-and-Logging>`_
|
||||
"""
|
||||
|
||||
__slots__ = ("message",)
|
||||
|
||||
|
|
@ -84,6 +89,9 @@ class TelegramError(Exception):
|
|||
class Forbidden(TelegramError):
|
||||
"""Raised when the bot has not enough rights to perform the requested action.
|
||||
|
||||
Examples:
|
||||
:any:`Raw API Bot <examples.rawapibot>`
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
This class was previously named ``Unauthorized``.
|
||||
"""
|
||||
|
|
@ -107,7 +115,11 @@ class InvalidToken(TelegramError):
|
|||
|
||||
|
||||
class NetworkError(TelegramError):
|
||||
"""Base class for exceptions due to networking errors."""
|
||||
"""Base class for exceptions due to networking errors.
|
||||
|
||||
Examples:
|
||||
:any:`Raw API Bot <examples.rawapibot>`
|
||||
"""
|
||||
|
||||
__slots__ = ()
|
||||
|
||||
|
|
@ -137,6 +149,10 @@ class ChatMigrated(TelegramError):
|
|||
"""
|
||||
Raised when the requested group chat migrated to supergroup and has a new chat id.
|
||||
|
||||
.. seealso:: `Storing Bot, User and Chat Related Data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Storing-bot%2C-user-and-\
|
||||
chat-related-data>`_,
|
||||
|
||||
Args:
|
||||
new_chat_id (:obj:`int`): The new chat id of the group.
|
||||
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ else:
|
|||
class AIORateLimiter(BaseRateLimiter[int]):
|
||||
"""
|
||||
Implementation of :class:`~telegram.ext.BaseRateLimiter` using the library
|
||||
`aiolimiter <https://aiolimiter.readthedocs.io/>`_.
|
||||
`aiolimiter <https://aiolimiter.readthedocs.io/en/stable>`_.
|
||||
|
||||
Important:
|
||||
If you want to use this class, you must install PTB with the optional requirement
|
||||
|
|
@ -90,6 +90,9 @@ class AIORateLimiter(BaseRateLimiter[int]):
|
|||
welcome you to implement your own subclass of :class:`~telegram.ext.BaseRateLimiter`.
|
||||
Feel free to check out the source code of this class for inspiration.
|
||||
|
||||
.. seealso:: `Avoiding Flood Limits <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Avoiding-flood-limits>`_
|
||||
|
||||
.. versionadded:: 20.0
|
||||
|
||||
Args:
|
||||
|
|
|
|||
|
|
@ -133,6 +133,14 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
finally:
|
||||
await application.shutdown()
|
||||
|
||||
Examples:
|
||||
:any:`Echo Bot <examples.echobot>`
|
||||
|
||||
.. seealso:: `Your First Bot <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Your-first-Bot>`_,
|
||||
`Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* Initialization is now done through the :class:`telegram.ext.ApplicationBuilder`.
|
||||
|
|
@ -146,19 +154,27 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
job_queue (:class:`telegram.ext.JobQueue`): Optional. The :class:`telegram.ext.JobQueue`
|
||||
instance to pass onto handler callbacks.
|
||||
chat_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for
|
||||
the chat.
|
||||
the chat. For each integer chat id, the corresponding value of this mapping is
|
||||
available as :attr:`telegram.ext.CallbackContext.chat_data` in handler callbacks for
|
||||
updates from that chat.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
:attr:`chat_data` is now read-only
|
||||
:attr:`chat_data` is now read-only. Note that the values of the mapping are still
|
||||
mutable, i.e. editing ``context.chat_data`` within a handler callback is possible
|
||||
(and encouraged), but editing the mapping ``application.chat_data`` itself is not.
|
||||
|
||||
.. tip::
|
||||
Manually modifying :attr:`chat_data` is almost never needed and unadvisable.
|
||||
|
||||
user_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for
|
||||
the user.
|
||||
the user. For each integer user id, the corresponding value of this mapping is
|
||||
available as :attr:`telegram.ext.CallbackContext.user_data` in handler callbacks for
|
||||
updates from that user.
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
:attr:`user_data` is now read-only
|
||||
:attr:`user_data` is now read-only. Note that the values of the mapping are still
|
||||
mutable, i.e. editing ``context.user_data`` within a handler callback is possible
|
||||
(and encouraged), but editing the mapping ``application.user_data`` itself is not.
|
||||
|
||||
.. tip::
|
||||
Manually modifying :attr:`user_data` is almost never needed and unadvisable.
|
||||
|
|
@ -315,6 +331,9 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
def concurrent_updates(self) -> int:
|
||||
""":obj:`int`: The number of concurrent updates that will be processed in parallel. A
|
||||
value of ``0`` indicates updates are *not* being processed concurrently.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
"""
|
||||
return self._concurrent_updates
|
||||
|
||||
|
|
@ -584,9 +603,12 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
If :attr:`post_shutdown` is set, it will be called after both :meth:`shutdown`
|
||||
and :meth:`telegram.ext.Updater.shutdown`.
|
||||
|
||||
.. include:: inclusions/application_run_tip.rst
|
||||
|
||||
.. seealso::
|
||||
:meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown`
|
||||
:meth:`telegram.ext.Updater.start_polling`, :meth:`run_webhook`
|
||||
:meth:`telegram.ext.Updater.start_polling`, :meth:`telegram.ext.Updater.stop`,
|
||||
:meth:`run_webhook`
|
||||
|
||||
Args:
|
||||
poll_interval (:obj:`float`, optional): Time to wait between polling updates from
|
||||
|
|
@ -677,7 +699,7 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
secret_token: str = None,
|
||||
) -> None:
|
||||
"""Convenience method that takes care of initializing and starting the app,
|
||||
polling updates from Telegram using :meth:`telegram.ext.Updater.start_webhook` and
|
||||
listening for updates from Telegram using :meth:`telegram.ext.Updater.start_webhook` and
|
||||
a graceful shutdown of the app on exit.
|
||||
|
||||
The app will shut down when :exc:`KeyboardInterrupt` or :exc:`SystemExit` is raised.
|
||||
|
|
@ -705,9 +727,13 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
|
||||
pip install python-telegram-bot[webhooks]
|
||||
|
||||
.. include:: inclusions/application_run_tip.rst
|
||||
|
||||
.. seealso::
|
||||
:meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown`
|
||||
:meth:`telegram.ext.Updater.start_webhook`, :meth:`run_polling`
|
||||
:meth:`telegram.ext.Updater.start_webhook`, :meth:`telegram.ext.Updater.stop`,
|
||||
:meth:`run_polling`,
|
||||
`Webhooks <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_
|
||||
|
||||
Args:
|
||||
listen (:obj:`str`, optional): IP-Address to listen on. Defaults to
|
||||
|
|
@ -852,6 +878,9 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
* If the application is currently running, tasks created by this method will be
|
||||
awaited with :meth:`stop`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Args:
|
||||
coroutine (:term:`coroutine function`): The coroutine to run as task.
|
||||
update (:obj:`object`, optional): If set, will be passed to :meth:`process_error`
|
||||
|
|
@ -968,6 +997,9 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
"""Processes a single update and marks the update to be updated by the persistence later.
|
||||
Exceptions raised by handler callbacks will be processed by :meth:`process_update`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
Persistence is now updated in an interval set by
|
||||
:attr:`telegram.ext.BasePersistence.update_interval`.
|
||||
|
|
@ -1207,6 +1239,10 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
to the asynchronous nature of these features. Please make sure that your program can
|
||||
avoid or handle such situations.
|
||||
|
||||
.. seealso:: `Storing Bot, User and Chat Related Data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Storing-bot%2C-user-and-\
|
||||
chat-related-data>`_,
|
||||
|
||||
Args:
|
||||
message (:class:`telegram.Message`, optional): A message with either
|
||||
:attr:`~telegram.Message.migrate_from_chat_id` or
|
||||
|
|
@ -1423,7 +1459,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
|||
Note:
|
||||
Attempts to add the same callback multiple times will be ignored.
|
||||
|
||||
.. seealso:: `Errorhandler Example <examples.errorhandlerbot.py>`_
|
||||
Examples:
|
||||
:any:`Errorhandler Bot <examples.errorhandlerbot>`
|
||||
|
||||
.. seealso:: `Exceptions, Warnings and Logging <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Exceptions%2C-Warnings-and-Logging>`_
|
||||
|
||||
Args:
|
||||
callback (:term:`coroutine function`): The callback function for this error handler.
|
||||
|
|
|
|||
|
|
@ -112,6 +112,11 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]):
|
|||
* Unless a custom :class:`telegram.Bot` instance is set via :meth:`bot`, :meth:`build` will
|
||||
use :class:`telegram.ext.ExtBot` for the bot.
|
||||
|
||||
.. seealso:: `Your First Bot <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Your-first-Bot>`_,
|
||||
`Builder Pattern for Application <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Builder-Pattern>`_
|
||||
|
||||
.. _`builder pattern`: https://en.wikipedia.org/wiki/Builder_pattern
|
||||
"""
|
||||
|
||||
|
|
@ -729,8 +734,8 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]):
|
|||
|
||||
pip install python-telegram-bot[callback-data]
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/python-telegram-bot\
|
||||
/python-telegram-bot/wiki/Arbitrary-callback_data>`_,
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_,
|
||||
:any:`examples.arbitrarycallbackdatabot`
|
||||
|
||||
Args:
|
||||
|
|
|
|||
|
|
@ -111,6 +111,11 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
|
|||
type of the argument of :meth:`refresh_bot_data` and the return value of
|
||||
:meth:`get_bot_data`.
|
||||
|
||||
.. seealso:: `Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Making Your Bot Persistent <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Making-your-bot-persistent>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
||||
|
|
|
|||
|
|
@ -37,6 +37,11 @@ class BaseRateLimiter(ABC, Generic[RLARGS]):
|
|||
Hint:
|
||||
Requests to :meth:`~telegram.Bot.get_updates` are never rate limited.
|
||||
|
||||
.. seealso:: `Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Avoiding Flood Limits <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Avoiding-flood-limits>`_
|
||||
|
||||
.. versionadded:: 20.0
|
||||
"""
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,13 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
|
|||
3. The type of :attr:`chat_data` (if :attr:`chat_data` is not :obj:`None`).
|
||||
4. The type of :attr:`bot_data` (if :attr:`bot_data` is not :obj:`None`).
|
||||
|
||||
.. seealso:: :attr:`telegram.ext.ContextTypes.DEFAULT_TYPE`
|
||||
Examples:
|
||||
* :any:`Context Types Bot <examples.contexttypesbot>`
|
||||
* :any:`Custom Webhook Bot <examples.customwebhookbot>`
|
||||
|
||||
.. seealso:: :attr:`telegram.ext.ContextTypes.DEFAULT_TYPE`,
|
||||
`Job Queue <https://github.com/python-telegram-bot/
|
||||
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
|
||||
|
||||
Args:
|
||||
application (:class:`telegram.ext.Application`): The application associated with this
|
||||
|
|
@ -138,6 +144,10 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
|
|||
def bot_data(self) -> BD:
|
||||
""":obj:`ContextTypes.bot_data`: Optional. An object that can be used to keep any data in.
|
||||
For each update it will be the same :attr:`ContextTypes.bot_data`. Defaults to :obj:`dict`.
|
||||
|
||||
.. seealso:: `Storing Bot, User and Chat Related Data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Storing-bot%2C-user-and-\
|
||||
chat-related-data>`_,
|
||||
"""
|
||||
return self.application.bot_data
|
||||
|
||||
|
|
@ -159,6 +169,10 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
|
|||
<https://github.com/python-telegram-bot/python-telegram-bot/wiki/
|
||||
Storing-bot,-user-and-chat-related-data#chat-migration>`_.
|
||||
|
||||
.. seealso:: `Storing Bot, User and Chat Related Data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Storing-bot%2C-user-and-\
|
||||
chat-related-data>`_,
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
The chat data is now also present in error handlers if the error is caused by a job.
|
||||
"""
|
||||
|
|
@ -178,6 +192,10 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
|
|||
For each update from the same user it will be the same :obj:`ContextTypes.user_data`.
|
||||
Defaults to :obj:`dict`.
|
||||
|
||||
.. seealso:: `Storing Bot, User and Chat Related Data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Storing-bot%2C-user-and\
|
||||
-chat-related-data>`_,
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
The user data is now also present in error handlers if the error is caused by a job.
|
||||
"""
|
||||
|
|
@ -225,6 +243,9 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
|
|||
Will *not* raise exceptions in case the data is not found in the cache.
|
||||
*Will* raise :exc:`KeyError` in case the callback query can not be found in the cache.
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
|
||||
Args:
|
||||
callback_query (:class:`telegram.CallbackQuery`): The callback query.
|
||||
|
||||
|
|
@ -365,6 +386,8 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
|
|||
:class:`telegram.ext.JobQueue`: The :class:`JobQueue` used by the
|
||||
:class:`telegram.ext.Application`.
|
||||
|
||||
.. seealso:: `Job Queue <https://github.com/python-telegram-bot/
|
||||
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
|
||||
"""
|
||||
return self._application.job_queue
|
||||
|
||||
|
|
|
|||
|
|
@ -44,6 +44,12 @@ class InvalidCallbackData(TelegramError):
|
|||
"""
|
||||
Raised when the received callback data has been tempered with or deleted from cache.
|
||||
|
||||
Examples:
|
||||
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
|
||||
.. versionadded:: 13.6
|
||||
|
||||
Args:
|
||||
|
|
@ -93,8 +99,8 @@ class CallbackDataCache:
|
|||
"""A custom cache for storing the callback data of a :class:`telegram.ext.ExtBot`. Internally,
|
||||
it keeps two mappings with fixed maximum size:
|
||||
|
||||
* One for mapping the data received in callback queries to the cached objects
|
||||
* One for mapping the IDs of received callback queries to the cached objects
|
||||
* One for mapping the data received in callback queries to the cached objects
|
||||
* One for mapping the IDs of received callback queries to the cached objects
|
||||
|
||||
The second mapping allows to manually drop data that has been cached for keyboards of messages
|
||||
sent via inline mode.
|
||||
|
|
@ -108,10 +114,14 @@ class CallbackDataCache:
|
|||
|
||||
pip install python-telegram-bot[callback-data]
|
||||
|
||||
Examples:
|
||||
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||
|
||||
.. seealso:: :attr:`telegram.ext.ExtBot.callback_data_cache`,
|
||||
`Arbitrary callback_data <https://github.com/python-telegram-bot/
|
||||
python-telegram-bot/wiki/Arbitrary-callback_data>`_,
|
||||
Arbitrary Callback Data Example <examples.arbitrarycallbackdatabot.html>
|
||||
`Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
|
||||
.. versionadded:: 13.6
|
||||
|
||||
|
|
|
|||
|
|
@ -81,12 +81,18 @@ class CallbackQueryHandler(BaseHandler[Update, CCT]):
|
|||
If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the
|
||||
:class:`telegram.CallbackQuery` update will not be handled.
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
|
||||
.. versionchanged:: 13.6
|
||||
Added support for arbitrary callback data.
|
||||
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
||||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
pattern (:func:`re.Pattern <re.compile>` | :obj:`callable` | :obj:`type`): Optional.
|
||||
|
|
|
|||
|
|
@ -66,6 +66,9 @@ class ChatJoinRequestHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
||||
|
|
|
|||
|
|
@ -35,7 +35,8 @@ class ChatMemberHandler(BaseHandler[Update, CCT]):
|
|||
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
|
||||
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
|
||||
|
||||
.. seealso:: `Chat Member Example <examples.chatmemberbot.html>`_
|
||||
Examples:
|
||||
:any:`Chat Member Bot <examples.chatmemberbot>`
|
||||
|
||||
.. versionadded:: 13.4
|
||||
|
||||
|
|
@ -56,6 +57,9 @@ class ChatMemberHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
chat_member_types (:obj:`int`, optional): Specifies if this handler should handle
|
||||
|
|
|
|||
|
|
@ -52,6 +52,9 @@ class ChosenInlineResultHandler(BaseHandler[Update, CCT]):
|
|||
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
||||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
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
|
||||
|
|
|
|||
|
|
@ -57,6 +57,10 @@ class CommandHandler(BaseHandler[Update, CCT]):
|
|||
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
|
||||
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
|
||||
|
||||
Examples:
|
||||
* :any:`Timer Bot <examples.timerbot>`
|
||||
* :any:`Error Handler Bot <examples.errorhandlerbot>`
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* Renamed the attribute ``command`` to :attr:`commands`, which now is always a
|
||||
|
|
@ -83,6 +87,9 @@ class CommandHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Raises:
|
||||
:exc:`ValueError`: When the command is too long or has illegal chars.
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,13 @@ class ContextTypes(Generic[CCT, UD, CD, BD]):
|
|||
Convenience class to gather customizable types of the :class:`telegram.ext.CallbackContext`
|
||||
interface.
|
||||
|
||||
.. seealso:: `ContextTypes Example <examples.contexttypesbot.html>`_
|
||||
Examples:
|
||||
:any:`ContextTypes Bot <examples.contexttypesbot>`
|
||||
|
||||
.. seealso:: `Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Storing Bot, User and Chat Related Data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Storing-bot%2C-user-and-chat-related-data>`_
|
||||
|
||||
.. versionadded:: 13.6
|
||||
|
||||
|
|
|
|||
|
|
@ -185,10 +185,11 @@ class ConversationHandler(BaseHandler[Update, CCT]):
|
|||
conversation. For an example on nested :class:`ConversationHandler` s, see
|
||||
:any:`examples.nestedconversationbot`.
|
||||
|
||||
.. seealso:: `Conversation Example <examples.conversationbot.html>`_,
|
||||
`Conversation Example 2 <examples.conversationbot2.html>`_,
|
||||
`Nested Conversation Example <examples.nestedconversationbot.html>`_,
|
||||
`Persistent Conversation Example <examples.persistentconversationbot.html>`_
|
||||
Examples:
|
||||
* :any:`Conversation Bot <examples.conversationbot>`
|
||||
* :any:`Conversation Bot 2 <examples.conversationbot2>`
|
||||
* :any:`Nested Conversation Bot <examples.nestedconversationbot>`
|
||||
* :any:`Persistent Conversation Bot <examples.persistentconversationbot>`
|
||||
|
||||
Args:
|
||||
entry_points (List[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler`
|
||||
|
|
@ -248,6 +249,9 @@ class ConversationHandler(BaseHandler[Update, CCT]):
|
|||
2. the value passed to this parameter (if any)
|
||||
3. :attr:`telegram.ext.Defaults.block` (if defaults are used)
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
No longer overrides the handlers settings. Resolution order was changed.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,6 +26,11 @@ from telegram._utils.datetime import UTC
|
|||
class Defaults:
|
||||
"""Convenience Class to gather all parameters with a (user defined) default value
|
||||
|
||||
.. seealso:: `Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Adding Defaults to Your Bot <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Adding-defaults-to-your-bot>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
Removed the argument and attribute ``timeout``. Specify default timeout behavior for the
|
||||
networking backend directly via :class:`telegram.ext.ApplicationBuilder` instead.
|
||||
|
|
|
|||
|
|
@ -43,6 +43,9 @@ class DictPersistence(BasePersistence):
|
|||
* This implementation of :class:`BasePersistence` does not handle data that cannot be
|
||||
serialized by :func:`json.dumps`.
|
||||
|
||||
.. seealso:: `Making Your Bot Persistent <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Making-your-bot-persistent>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
||||
|
||||
|
|
|
|||
|
|
@ -118,9 +118,11 @@ class ExtBot(Bot, Generic[RLARGS]):
|
|||
* The method :meth:`~telegram.Bot.get_updates` is the only method that does not have the
|
||||
additional argument, as this method will never be rate limited.
|
||||
|
||||
.. seealso:: `Arbitrary Callback Example <examples.arbitrarycallbackdatabot.html>`_,
|
||||
`Arbitrary callback_data <https://github.com/python-telegram-bot/
|
||||
python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
Examples:
|
||||
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
|
||||
.. versionadded:: 13.6
|
||||
|
||||
|
|
@ -134,9 +136,11 @@ class ExtBot(Bot, Generic[RLARGS]):
|
|||
be used if not set explicitly in the bot methods.
|
||||
arbitrary_callback_data (:obj:`bool` | :obj:`int`, optional): Whether to
|
||||
allow arbitrary objects as callback data for :class:`telegram.InlineKeyboardButton`.
|
||||
Pass an integer to specify the maximum number of objects cached in memory. For more
|
||||
details, please see our `wiki <https://github.com/python-telegram-bot\
|
||||
/python-telegram-bot/wiki/Arbitrary-callback_data>`_. Defaults to :obj:`False`.
|
||||
Pass an integer to specify the maximum number of objects cached in memory.
|
||||
Defaults to :obj:`False`.
|
||||
|
||||
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||
rate_limiter (:class:`telegram.ext.BaseRateLimiter`, optional): A rate limiter to use for
|
||||
limiting the number of requests made by the bot per time interval.
|
||||
|
||||
|
|
@ -226,6 +230,9 @@ class ExtBot(Bot, Generic[RLARGS]):
|
|||
""":class:`telegram.ext.CallbackDataCache`: Optional. The cache for
|
||||
objects passed as callback data for :class:`telegram.InlineKeyboardButton`.
|
||||
|
||||
Examples:
|
||||
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
* This property is now read-only.
|
||||
* This property is now optional and can be :obj:`None` if
|
||||
|
|
|
|||
|
|
@ -54,6 +54,9 @@ class BaseHandler(Generic[UT, CCT], ABC):
|
|||
also used for the mentioned method arguments. That way, a type checker can check whether
|
||||
this handler fits the definition of the :class:`~Application`.
|
||||
|
||||
.. seealso:: `Types of Handlers <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Types-of-Handlers>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* The attribute ``run_async`` is now :paramref:`block`.
|
||||
|
|
@ -72,6 +75,9 @@ class BaseHandler(Generic[UT, CCT], ABC):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
||||
|
|
|
|||
|
|
@ -46,7 +46,9 @@ class InlineQueryHandler(BaseHandler[Update, CCT]):
|
|||
chats and may not be set for inline queries coming from third-party clients. These
|
||||
updates won't be handled, if :attr:`chat_types` is passed.
|
||||
|
||||
.. seealso:: `Inlinebot Example <examples.inlinebot.html>`_
|
||||
Examples:
|
||||
:any:`Inline Bot <examples.inlinebot>`
|
||||
|
||||
|
||||
Args:
|
||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
||||
|
|
@ -63,6 +65,9 @@ class InlineQueryHandler(BaseHandler[Update, CCT]):
|
|||
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
||||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
chat_types (List[:obj:`str`], optional): List of allowed chat types. If passed, will only
|
||||
handle inline queries with the appropriate :attr:`telegram.InlineQuery.chat_type`.
|
||||
|
||||
|
|
|
|||
|
|
@ -53,9 +53,13 @@ class JobQueue:
|
|||
|
||||
pip install python-telegram-bot[job-queue]
|
||||
|
||||
Examples:
|
||||
:any:`Timer Bot <examples.timerbot>`
|
||||
|
||||
.. seealso:: :attr:`telegram.ext.Application.job_queue`,
|
||||
:attr:`telegram.ext.CallbackContext.job_queue`,
|
||||
`Timerbot Example <examples.timerbot.html>`_,
|
||||
`Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Job Queue <https://github.com/python-telegram-bot/
|
||||
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
|
||||
|
||||
|
|
@ -639,6 +643,9 @@ class Job:
|
|||
This class should not be instantiated manually.
|
||||
Use the methods of :class:`telegram.ext.JobQueue` to schedule jobs.
|
||||
|
||||
.. seealso:: `Job Queue <https://github.com/python-telegram-bot/
|
||||
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* Removed argument and attribute ``job_queue``.
|
||||
|
|
|
|||
|
|
@ -49,6 +49,9 @@ class MessageHandler(BaseHandler[Update, CCT]):
|
|||
:attr:`telegram.Update.channel_post` and :attr:`telegram.Update.edited_channel_post`.
|
||||
If you don't want or need any of those pass ``~filters.UpdateType.*`` in the filter
|
||||
argument.
|
||||
|
||||
.. seealso:: `Advanced Filters <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Advanced-Filters>`_
|
||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
||||
called when :meth:`check_update` has determined that an update should be processed by
|
||||
this handler. Callback signature::
|
||||
|
|
@ -61,6 +64,9 @@ class MessageHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
filters (:class:`telegram.ext.filters.BaseFilter`): Only allow updates with these Filters.
|
||||
See :mod:`telegram.ext.filters` for a full list of all available filters.
|
||||
|
|
|
|||
|
|
@ -130,6 +130,12 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
|
|||
:attr:`~BasePersistence.bot` will be replaced by a placeholder before pickling and
|
||||
:attr:`~BasePersistence.bot` will be inserted back when loading the data.
|
||||
|
||||
Examples:
|
||||
:any:`Persistent Conversation Bot <examples.persistentconversationbot>`
|
||||
|
||||
.. seealso:: `Making Your Bot Persistent <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Making-your-bot-persistent>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
||||
|
|
|
|||
|
|
@ -32,7 +32,8 @@ class PollAnswerHandler(BaseHandler[Update, CCT]):
|
|||
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
|
||||
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
|
||||
|
||||
.. seealso:: `Pollbot EXample <examples.pollbot.html>`_
|
||||
Examples:
|
||||
:any:`Poll Bot <examples.pollbot>`
|
||||
|
||||
Args:
|
||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
||||
|
|
@ -47,6 +48,9 @@ class PollAnswerHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
||||
|
|
|
|||
|
|
@ -32,7 +32,8 @@ class PollHandler(BaseHandler[Update, CCT]):
|
|||
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
|
||||
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
|
||||
|
||||
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
|
||||
Examples:
|
||||
:any:`Poll Bot <examples.pollbot>`
|
||||
|
||||
Args:
|
||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
||||
|
|
@ -47,6 +48,9 @@ class PollHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
||||
|
|
|
|||
|
|
@ -31,7 +31,8 @@ class PreCheckoutQueryHandler(BaseHandler[Update, CCT]):
|
|||
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
|
||||
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
|
||||
|
||||
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
|
||||
Examples:
|
||||
:any:`Payment Bot <examples.paymentbot>`
|
||||
|
||||
Args:
|
||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
||||
|
|
@ -46,6 +47,9 @@ class PreCheckoutQueryHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
||||
|
|
|
|||
|
|
@ -105,6 +105,9 @@ class PrefixHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
commands (FrozenSet[:obj:`str`]): The commands that this handler will listen for, i.e. the
|
||||
combinations of :paramref:`prefix` and :paramref:`command`.
|
||||
|
|
|
|||
|
|
@ -31,7 +31,8 @@ class ShippingQueryHandler(BaseHandler[Update, CCT]):
|
|||
When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
|
||||
attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
|
||||
|
||||
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
|
||||
Examples:
|
||||
:any:`Payment Bot <examples.paymentbot>`
|
||||
|
||||
Args:
|
||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
||||
|
|
@ -46,6 +47,9 @@ class ShippingQueryHandler(BaseHandler[Update, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
||||
|
|
|
|||
|
|
@ -57,6 +57,9 @@ class StringCommandHandler(BaseHandler[str, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
command (:obj:`str`): The command this handler should listen for.
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
|
|
|
|||
|
|
@ -60,6 +60,9 @@ class StringRegexHandler(BaseHandler[str, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
|
||||
callback (:term:`coroutine function`): The callback function for this handler.
|
||||
|
|
|
|||
|
|
@ -53,6 +53,9 @@ class TypeHandler(BaseHandler[UT, CCT]):
|
|||
be awaited before processing the next handler in
|
||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||
|
||||
.. seealso:: `Concurrency <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||
|
||||
Attributes:
|
||||
type (:external:class:`type`): The :external:class:`type` of updates this handler should
|
||||
process.
|
||||
|
|
|
|||
|
|
@ -65,6 +65,11 @@ class Updater(AbstractAsyncContextManager):
|
|||
finally:
|
||||
await updater.shutdown()
|
||||
|
||||
.. seealso:: `Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Builder Pattern <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Builder-Pattern>`_
|
||||
|
||||
.. versionchanged:: 20.0
|
||||
|
||||
* Removed argument and attribute ``user_sig_handler``
|
||||
|
|
@ -392,6 +397,9 @@ class Updater(AbstractAsyncContextManager):
|
|||
|
||||
pip install python-telegram-bot[webhooks]
|
||||
|
||||
.. seealso:: `Webhooks <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_
|
||||
|
||||
.. versionchanged:: 13.4
|
||||
:meth:`start_webhook` now *always* calls :meth:`telegram.Bot.set_webhook`, so pass
|
||||
``webhook_url`` instead of calling ``updater.bot.set_webhook(webhook_url)`` manually.
|
||||
|
|
|
|||
|
|
@ -28,11 +28,11 @@ This module contains filters for use with :class:`telegram.ext.MessageHandler`,
|
|||
:mod:`~telegram.ext.filters` module.
|
||||
#. The names of all filters has been updated:
|
||||
|
||||
* Filter classes which are ready for use, e.g ``Filters.all`` are now capitalized, e.g
|
||||
``filters.ALL``.
|
||||
* Filters which need to be initialized are now in CamelCase. E.g. ``filters.User(...)``.
|
||||
* Filters which do both (like ``Filters.text``) are now split as ready-to-use version
|
||||
``filters.TEXT`` and class version ``filters.Text(...)``.
|
||||
* Filter classes which are ready for use, e.g ``Filters.all`` are now capitalized, e.g
|
||||
``filters.ALL``.
|
||||
* Filters which need to be initialized are now in CamelCase. E.g. ``filters.User(...)``.
|
||||
* Filters which do both (like ``Filters.text``) are now split as ready-to-use version
|
||||
``filters.TEXT`` and class version ``filters.Text(...)``.
|
||||
|
||||
"""
|
||||
|
||||
|
|
@ -231,6 +231,9 @@ class MessageFilter(BaseFilter):
|
|||
|
||||
Please see :class:`BaseFilter` for details on how to create custom filters.
|
||||
|
||||
.. seealso:: `Advanced Filters <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Advanced-Filters>`_
|
||||
|
||||
Attributes:
|
||||
name (:obj:`str`): Name for this filter. Defaults to the type of filter.
|
||||
data_filter (:obj:`bool`): Whether this filter is a data filter. A data filter should
|
||||
|
|
@ -1527,6 +1530,9 @@ class Regex(MessageFilter):
|
|||
With a :attr:`telegram.Message.text` of `x`, will only ever return the matches for the
|
||||
first filter, since the second one is never evaluated.
|
||||
|
||||
.. seealso:: `Types of Handlers <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Types-of-Handlers>`_
|
||||
|
||||
Args:
|
||||
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
|
||||
"""
|
||||
|
|
|
|||
|
|
@ -72,6 +72,8 @@ def escape_markdown(text: str, version: int = 1, entity_type: str = None) -> str
|
|||
|
||||
def mention_html(user_id: Union[int, str], name: str) -> str:
|
||||
"""
|
||||
Helper function to create a user mention as HTML tag.
|
||||
|
||||
Args:
|
||||
user_id (:obj:`int`): The user's id which you want to mention.
|
||||
name (:obj:`str`): The name the mention is showing.
|
||||
|
|
@ -84,6 +86,8 @@ def mention_html(user_id: Union[int, str], name: str) -> str:
|
|||
|
||||
def mention_markdown(user_id: Union[int, str], name: str, version: int = 1) -> str:
|
||||
"""
|
||||
Helper function to create a user mention in Markdown syntax.
|
||||
|
||||
Args:
|
||||
user_id (:obj:`int`): The user's id which you want to mention.
|
||||
name (:obj:`str`): The name the mention is showing.
|
||||
|
|
@ -110,7 +114,7 @@ def effective_message_type(entity: Union["Message", "Update"]) -> Optional[str]:
|
|||
|
||||
Returns:
|
||||
:obj:`str` | :obj:`None`: One of :class:`telegram.constants.MessageType` if the entity
|
||||
contains a message that matches one of those types. :obj:`None` otherwise.
|
||||
contains a message that matches one of those types. :obj:`None` otherwise.
|
||||
|
||||
"""
|
||||
# Importing on file-level yields cyclic Import Errors
|
||||
|
|
@ -146,19 +150,18 @@ def create_deep_linked_url(bot_username: str, payload: str = None, group: bool =
|
|||
``CommandHandler("start", callback, filters=filters.Regex('payload'))``
|
||||
|
||||
Examples:
|
||||
``create_deep_linked_url(bot.get_me().username, "some-params")``
|
||||
|
||||
.. seealso:: `Deeplinking Example <examples.deeplinking.html>`_
|
||||
* ``create_deep_linked_url(bot.get_me().username, "some-params")``
|
||||
* :any:`Deep Linking <examples.deeplinking>`
|
||||
|
||||
Args:
|
||||
bot_username (:obj:`str`): The username to link to
|
||||
payload (:obj:`str`, optional): Parameters to encode in the created URL
|
||||
bot_username (:obj:`str`): The username to link to.
|
||||
payload (:obj:`str`, optional): Parameters to encode in the created URL.
|
||||
group (:obj:`bool`, optional): If :obj:`True` the user is prompted to select a group to
|
||||
add the bot to. If :obj:`False`, opens a one-on-one conversation with the bot.
|
||||
Defaults to :obj:`False`.
|
||||
|
||||
Returns:
|
||||
:obj:`str`: An URL to start the bot with specific parameters
|
||||
:obj:`str`: An URL to start the bot with specific parameters.
|
||||
"""
|
||||
if bot_username is None or len(bot_username) <= 3:
|
||||
raise ValueError("You must provide a valid bot_username.")
|
||||
|
|
|
|||
|
|
@ -73,6 +73,11 @@ class BaseRequest(
|
|||
To use a custom library for this, you can override :meth:`parse_json_payload` and implement
|
||||
custom logic to encode the keys of :attr:`telegram.request.RequestData.parameters`.
|
||||
|
||||
.. seealso:: `Architecture Overview <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||
`Builder Pattern <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Builder-Pattern>`_
|
||||
|
||||
.. versionadded:: 20.0
|
||||
"""
|
||||
|
||||
|
|
|
|||
|
|
@ -28,6 +28,9 @@ class PTBUserWarning(UserWarning):
|
|||
"""
|
||||
Custom user warning class used for warnings in this library.
|
||||
|
||||
.. seealso:: `Exceptions, Warnings and Logging <https://github.com/\
|
||||
python-telegram-bot/python-telegram-bot/wiki/Exceptions%2C-Warnings-and-Logging>`_
|
||||
|
||||
.. versionadded:: 20.0
|
||||
"""
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue