mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2025-03-29 17:50:32 +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
|
.. 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
|
$ cd python-telegram-bot
|
||||||
|
|
||||||
3. Add a track to the original repository:
|
3. Add a track to the original repository:
|
||||||
|
|
|
||||||
|
|
@ -21,6 +21,31 @@ python:
|
||||||
- requirements: docs/requirements-docs.txt
|
- requirements: docs/requirements-docs.txt
|
||||||
|
|
||||||
build:
|
build:
|
||||||
os: ubuntu-20.04
|
os: ubuntu-22.04
|
||||||
tools:
|
tools:
|
||||||
python: "3" # latest stable cpython version
|
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==5.3.0
|
||||||
sphinx-pypi-upload
|
sphinx-pypi-upload
|
||||||
furo==2022.9.29
|
furo==2022.9.29
|
||||||
|
git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search
|
||||||
sphinx-paramlinks==0.5.4
|
sphinx-paramlinks==0.5.4
|
||||||
sphinxcontrib-mermaid==0.7.1
|
sphinxcontrib-mermaid==0.7.1
|
||||||
|
|
@ -5,7 +5,7 @@ import subprocess
|
||||||
import sys
|
import sys
|
||||||
from enum import Enum
|
from enum import Enum
|
||||||
from pathlib import Path
|
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,
|
# 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
|
# 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__
|
release = "20.0a4" # telegram.__version__
|
||||||
|
|
||||||
# If your documentation needs a minimal Sphinx version, state it here.
|
# 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
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
|
@ -46,6 +46,7 @@ extensions = [
|
||||||
"sphinx.ext.linkcode",
|
"sphinx.ext.linkcode",
|
||||||
"sphinx_paramlinks",
|
"sphinx_paramlinks",
|
||||||
"sphinxcontrib.mermaid",
|
"sphinxcontrib.mermaid",
|
||||||
|
"sphinx_search.extension",
|
||||||
]
|
]
|
||||||
|
|
||||||
# Use intersphinx to reference the python builtin library docs
|
# 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,
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
html_static_path = ["_static"]
|
html_static_path = ["_static"]
|
||||||
html_css_files = [
|
html_css_files = ["style_external_link.css", "style_mermaid_diagrams.css"]
|
||||||
"style_external_link.css",
|
|
||||||
"style_mermaid_diagrams.css",
|
html_permalinks_icon = "¶" # Furo's default permalink icon is `#` which doesn't look great imo.
|
||||||
]
|
|
||||||
html_permalinks_icon = "¶" # Furo's default permalink icon is `#`` which doesn't look great imo.
|
|
||||||
|
|
||||||
# Output file base name for HTML help builder.
|
# Output file base name for HTML help builder.
|
||||||
htmlhelp_basename = "python-telegram-bot-doc"
|
htmlhelp_basename = "python-telegram-bot-doc"
|
||||||
|
|
@ -260,6 +259,7 @@ latex_logo = "ptb-logo_1024.png"
|
||||||
# (source start file, name, description, authors, manual section).
|
# (source start file, name, description, authors, manual section).
|
||||||
man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)]
|
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 -------------------------------------------
|
# -- Options for Texinfo output -------------------------------------------
|
||||||
|
|
||||||
|
|
@ -378,12 +378,98 @@ line_numbers = {}
|
||||||
file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
|
file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
|
||||||
import telegram.ext # Needed for checking if an object is a BaseFilter
|
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):
|
write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"]
|
||||||
"""We misuse this autodoc hook to get the file names & line numbers because we have access
|
read_timeout_sub = [
|
||||||
to the actual object here.
|
":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
|
# In linkcode_resolve we'll resolve to the `__init__` or module instead
|
||||||
if what == "attribute":
|
if what == "attribute":
|
||||||
return
|
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
|
:align: left
|
||||||
:widths: 1 4
|
: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`
|
* - :attr:`~telegram.Bot.bot`
|
||||||
- The user instance of the bot as returned by :meth:`~telegram.Bot.get_me`
|
- The user instance of the bot as returned by :meth:`~telegram.Bot.get_me`
|
||||||
* - :attr:`~telegram.Bot.can_join_groups`
|
* - :attr:`~telegram.Bot.can_join_groups`
|
||||||
|
|
@ -310,8 +314,12 @@
|
||||||
- The username of the bot, without leading ``@``
|
- The username of the bot, without leading ``@``
|
||||||
* - :attr:`~telegram.Bot.link`
|
* - :attr:`~telegram.Bot.link`
|
||||||
- The t.me link of the bot
|
- 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`
|
* - :attr:`~telegram.Bot.supports_inline_queries`
|
||||||
- Whether the bot supports inline queries
|
- Whether the bot supports inline queries
|
||||||
|
* - :attr:`~telegram.Bot.token`
|
||||||
|
- Bot's unique authentication token
|
||||||
|
|
||||||
.. raw:: html
|
.. 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::
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
|
||||||
telegram.ext.application
|
telegram.ext.application
|
||||||
telegram.ext.applicationbuilder
|
telegram.ext.applicationbuilder
|
||||||
|
|
|
||||||
|
|
@ -7,88 +7,14 @@ Version Constants
|
||||||
.. automodule:: telegram
|
.. automodule:: telegram
|
||||||
:members: __version__, __version_info__, __bot_api_version__, __bot_api_version_info__
|
:members: __version__, __version_info__, __bot_api_version__, __bot_api_version_info__
|
||||||
|
|
||||||
Available Types
|
Classes in this package
|
||||||
---------------
|
-----------------------
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
|
||||||
telegram.animation
|
|
||||||
telegram.audio
|
|
||||||
telegram.bot
|
telegram.bot
|
||||||
telegram.botcommand
|
telegram.at-tree.rst
|
||||||
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.stickers-tree.rst
|
telegram.stickers-tree.rst
|
||||||
telegram.inline-tree.rst
|
telegram.inline-tree.rst
|
||||||
telegram.payments-tree.rst
|
telegram.payments-tree.rst
|
||||||
|
|
|
||||||
|
|
@ -4,4 +4,4 @@ telegram.TelegramObject
|
||||||
.. autoclass:: telegram.TelegramObject
|
.. autoclass:: telegram.TelegramObject
|
||||||
:members:
|
:members:
|
||||||
:show-inheritance:
|
: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|
|
.. |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|
|
.. |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
|
.. versionadded:: 13.7
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||||
target supergroup (in the format ``@supergroupusername``)
|
|
||||||
Attributes:
|
Attributes:
|
||||||
type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT`.
|
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
|
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||||
target supergroup (in the format ``@supergroupusername``)
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
__slots__ = ("chat_id",)
|
__slots__ = ("chat_id",)
|
||||||
|
|
@ -210,12 +209,10 @@ class BotCommandScopeChatAdministrators(BotCommandScope):
|
||||||
.. versionadded:: 13.7
|
.. versionadded:: 13.7
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||||
target supergroup (in the format ``@supergroupusername``)
|
|
||||||
Attributes:
|
Attributes:
|
||||||
type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_ADMINISTRATORS`.
|
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
|
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||||
target supergroup (in the format ``@supergroupusername``)
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
__slots__ = ("chat_id",)
|
__slots__ = ("chat_id",)
|
||||||
|
|
@ -238,14 +235,12 @@ class BotCommandScopeChatMember(BotCommandScope):
|
||||||
.. versionadded:: 13.7
|
.. versionadded:: 13.7
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
|
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||||
target supergroup (in the format ``@supergroupusername``)
|
|
||||||
user_id (:obj:`int`): Unique identifier of the target user.
|
user_id (:obj:`int`): Unique identifier of the target user.
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_MEMBER`.
|
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
|
chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
|
||||||
target supergroup (in the format ``@supergroupusername``)
|
|
||||||
user_id (:obj:`int`): Unique identifier of the target user.
|
user_id (:obj:`int`): Unique identifier of the target user.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -149,21 +149,28 @@ class Chat(TelegramObject):
|
||||||
|
|
||||||
.. versionadded:: 20.0
|
.. versionadded:: 20.0
|
||||||
Attributes:
|
Attributes:
|
||||||
id (:obj:`int`): Unique identifier for this chat.
|
id (:obj:`int`): Unique identifier for this chat. This number may be greater than 32 bits
|
||||||
type (:obj:`str`): Type of chat.
|
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.
|
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.
|
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.
|
last_name (:obj:`str`): Optional. Last name of the other party in a private chat.
|
||||||
photo (:class:`telegram.ChatPhoto`): Optional. Chat photo.
|
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
|
bio (:obj:`str`): Optional. Bio of the other party in a private chat. Returned only in
|
||||||
:meth:`telegram.Bot.get_chat`.
|
:meth:`telegram.Bot.get_chat`.
|
||||||
has_private_forwards (:obj:`bool`): Optional. :obj:`True`, if privacy settings of the other
|
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
|
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
|
.. versionadded:: 13.9
|
||||||
description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats.
|
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
|
invite_link (:obj:`str`): Optional. Primary invite link, for groups, supergroups and
|
||||||
channel. Returned only in :meth:`telegram.Bot.get_chat`.
|
channel. Returned only in :meth:`telegram.Bot.get_chat`.
|
||||||
pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message
|
pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message
|
||||||
|
|
@ -179,12 +186,13 @@ class Chat(TelegramObject):
|
||||||
|
|
||||||
.. versionadded:: 13.4
|
.. versionadded:: 13.4
|
||||||
has_protected_content (:obj:`bool`): Optional. :obj:`True`, if messages from the chat can't
|
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
|
.. versionadded:: 13.9
|
||||||
sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set.
|
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
|
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
|
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
|
discussion group identifier for a channel and vice versa; for supergroups and channel
|
||||||
chats. Returned only in :meth:`telegram.Bot.get_chat`.
|
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
|
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.
|
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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -44,6 +44,9 @@ class ChatMemberUpdated(TelegramObject):
|
||||||
Note:
|
Note:
|
||||||
In Python :keyword:`from` is a reserved word use :paramref:`from_user` instead.
|
In Python :keyword:`from` is a reserved word use :paramref:`from_user` instead.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
:any:`Chat Member Bot <examples.chatmemberbot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
chat (:class:`telegram.Chat`): Chat the user belongs to.
|
chat (:class:`telegram.Chat`): Chat the user belongs to.
|
||||||
from_user (:class:`telegram.User`): Performer of the action, which resulted in the change.
|
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`.
|
* After Bot API 6.1, only ``HTTPS`` links will be allowed in :paramref:`login_url`.
|
||||||
|
|
||||||
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
|
Examples:
|
||||||
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_,
|
* :any:`Inline Keyboard 1 <examples.inlinekeyboard>`
|
||||||
:class:`telegram.InlineKeyboardMarkup`
|
* :any:`Inline Keyboard 2 <examples.inlinekeyboard2>`
|
||||||
|
|
||||||
|
.. seealso:: :class:`telegram.InlineKeyboardMarkup`
|
||||||
|
|
||||||
.. versionchanged:: 20.0
|
.. versionchanged:: 20.0
|
||||||
:attr:`web_app` is considered as well when comparing objects of this type in terms of
|
:attr:`web_app` is considered as well when comparing objects of this type in terms of
|
||||||
|
|
@ -90,6 +92,9 @@ class InlineKeyboardButton(TelegramObject):
|
||||||
Tip:
|
Tip:
|
||||||
The value entered here will be available in :attr:`telegram.CallbackQuery.data`.
|
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
|
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
|
<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
|
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
|
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.
|
considered equal, if their size of :attr:`inline_keyboard` and all the buttons are equal.
|
||||||
|
|
||||||
.. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
|
Examples:
|
||||||
`Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_
|
* :any:`Inline Keyboard 1 <examples.inlinekeyboard>`
|
||||||
|
* :any:`Inline Keyboard 2 <examples.inlinekeyboard2>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
|
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
|
All URLs passed in inline query results will be available to end users and therefore must
|
||||||
be assumed to be *public*.
|
be assumed to be *public*.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
:any:`Inline Bot <examples.inlinebot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
type (:obj:`str`): Type of the result.
|
type (:obj:`str`): Type of the result.
|
||||||
id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
|
id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
|
||||||
|
|
|
||||||
|
|
@ -32,7 +32,8 @@ if TYPE_CHECKING:
|
||||||
class InlineQueryResultArticle(InlineQueryResult):
|
class InlineQueryResultArticle(InlineQueryResult):
|
||||||
"""This object represents a Telegram InlineQueryResultArticle.
|
"""This object represents a Telegram InlineQueryResultArticle.
|
||||||
|
|
||||||
.. seealso:: `Inline Example <examples.inlinebot.html>`_
|
Examples:
|
||||||
|
:any:`Inline Bot <examples.inlinebot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
|
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
|
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.
|
considered equal, if their :attr:`message_text` is equal.
|
||||||
|
|
||||||
.. seealso:: `Inline Example <examples.inlinebot.html>`_
|
Examples:
|
||||||
|
:any:`Inline Bot <examples.inlinebot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
message_text (:obj:`str`): Text of the message to be sent,
|
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
|
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||||
considered equal, if their :attr:`type` is equal.
|
considered equal, if their :attr:`type` is equal.
|
||||||
|
|
||||||
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
|
Examples:
|
||||||
|
:any:`Poll Bot <examples.pollbot>`
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
type (:obj:`str`): Optional. If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be
|
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
|
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.
|
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
|
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
|
messages from anonymous group administrators, the linked channel for messages
|
||||||
automatically forwarded to the discussion group. For backward compatibility,
|
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
|
: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.
|
or from anonymous administrators, information about the original sender chat.
|
||||||
forward_from_message_id (:obj:`int`, optional): For forwarded channel posts, identifier of
|
forward_from_message_id (:obj:`int`, optional): For forwarded channel posts, identifier of
|
||||||
the original message in the channel.
|
the original message in the channel.
|
||||||
forward_sender_name (:obj:`str`, optional): Sender's name for messages forwarded from users
|
forward_sender_name (:obj:`str`, optional): Sender's name for messages forwarded from
|
||||||
who disallow adding a link to their account in forwarded messages.
|
users who disallow adding a link to their account in forwarded messages.
|
||||||
forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the
|
forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the
|
||||||
original message was sent in Unix time. Converted to :class:`datetime.datetime`.
|
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
|
is_automatic_forward (:obj:`bool`, optional): :obj:`True`, if the message is a channel
|
||||||
that was automatically forwarded to the connected discussion group.
|
post that was automatically forwarded to the connected discussion group.
|
||||||
|
|
||||||
.. versionadded:: 13.9
|
.. versionadded:: 13.9
|
||||||
reply_to_message (:class:`telegram.Message`, optional): For replies, the original message.
|
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
|
edit_date (:class:`datetime.datetime`, optional): Date the message was last edited in Unix
|
||||||
time. Converted to :class:`datetime.datetime`.
|
time. Converted to :class:`datetime.datetime`.
|
||||||
has_protected_content (:obj:`bool`, optional): :obj:`True`, if the message can't be
|
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
|
media_group_id (:obj:`str`, optional): The unique identifier of a media message group this
|
||||||
message belongs to.
|
message belongs to.
|
||||||
text (:obj:`str`, optional): For text messages, the actual UTF-8 text of the message,
|
text (:obj:`str`, optional): For text messages, the actual UTF-8 text of the message,
|
||||||
0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH`
|
0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters.
|
||||||
characters.
|
|
||||||
entities (List[:class:`telegram.MessageEntity`], optional): For text messages, special
|
entities (List[:class:`telegram.MessageEntity`], optional): For text messages, special
|
||||||
entities like usernames, URLs, bot commands, etc. that appear in the text. See
|
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.
|
: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_entities (List[:class:`telegram.MessageEntity`], optional): For messages with a
|
||||||
Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the
|
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`
|
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
|
audio (:class:`telegram.Audio`, optional): Message is an audio file, information
|
||||||
about the file.
|
about the file.
|
||||||
document (:class:`telegram.Document`, optional): Message is a general file, information
|
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
|
about the animation. For backward compatibility, when this field is set, the document
|
||||||
field will also be set.
|
field will also be set.
|
||||||
game (:class:`telegram.Game`, optional): Message is a game, information about the game.
|
game (:class:`telegram.Game`, optional): Message is a game, information about the game.
|
||||||
photo (List[:class:`telegram.PhotoSize`], optional): Message is a photo, available
|
photo (List[:class:`telegram.PhotoSize`], optional): Message is a photo, available sizes
|
||||||
sizes of the photo.
|
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
|
sticker (:class:`telegram.Sticker`, optional): Message is a sticker, information
|
||||||
about the sticker.
|
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
|
voice (:class:`telegram.Voice`, optional): Message is a voice message, information about
|
||||||
the file.
|
the file.
|
||||||
video_note (:class:`telegram.VideoNote`, optional): Message is a video note, information
|
video_note (:class:`telegram.VideoNote`, optional): Message is a video note, information
|
||||||
about the video message.
|
about the video message.
|
||||||
new_chat_members (List[:class:`telegram.User`], optional): New members that were added to
|
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
|
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
|
caption (:obj:`str`, optional): Caption for the animation, audio, document, photo, video
|
||||||
or voice, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters.
|
or voice, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters.
|
||||||
contact (:class:`telegram.Contact`, optional): Message is a shared contact, information
|
contact (:class:`telegram.Contact`, optional): Message is a shared contact, information
|
||||||
about the contact.
|
about the contact.
|
||||||
location (:class:`telegram.Location`, optional): Message is a shared location, information
|
location (:class:`telegram.Location`, optional): Message is a shared location, information
|
||||||
about the location.
|
about the location.
|
||||||
venue (:class:`telegram.Venue`, optional): Message is a venue, information about the venue.
|
venue (:class:`telegram.Venue`, optional): Message is a venue, information about the
|
||||||
For backward compatibility, when this field is set, the location field will also be
|
venue. For backward compatibility, when this field is set, the location field will
|
||||||
set.
|
also be set.
|
||||||
left_chat_member (:class:`telegram.User`, optional): A member was removed from the group,
|
left_chat_member (:class:`telegram.User`, optional): A member was removed from the group,
|
||||||
information about them (this member may be the bot itself).
|
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_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
|
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.
|
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.
|
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
|
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.
|
optional): Service message: auto-delete timer settings changed in the chat.
|
||||||
|
|
||||||
.. versionadded:: 13.4
|
.. versionadded:: 13.4
|
||||||
migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup with
|
migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup
|
||||||
the specified identifier. This number may be greater than 32 bits and some programming
|
with the specified identifier.
|
||||||
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_from_chat_id (:obj:`int`, optional): The supergroup has been migrated from a group
|
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
|
with the specified identifier.
|
||||||
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.
|
|
||||||
pinned_message (:class:`telegram.Message`, optional): Specified message was pinned. Note
|
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`
|
that the Message object in this field will not contain further
|
||||||
fields even if it is itself a reply.
|
:attr:`reply_to_message` fields even if it is itself a reply.
|
||||||
invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment,
|
invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment,
|
||||||
information about the invoice.
|
information about the invoice.
|
||||||
successful_payment (:class:`telegram.SuccessfulPayment`, optional): Message is a service
|
successful_payment (:class:`telegram.SuccessfulPayment`, optional): Message is a service
|
||||||
|
|
@ -215,13 +213,15 @@ class Message(TelegramObject):
|
||||||
has logged in.
|
has logged in.
|
||||||
forward_signature (:obj:`str`, optional): For messages forwarded from channels, signature
|
forward_signature (:obj:`str`, optional): For messages forwarded from channels, signature
|
||||||
of the post author if present.
|
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.
|
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.
|
passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data.
|
||||||
poll (:class:`telegram.Poll`, optional): Message is a native poll,
|
poll (:class:`telegram.Poll`, optional): Message is a native poll,
|
||||||
information about the poll.
|
information about the poll.
|
||||||
dice (:class:`telegram.Dice`, optional): Message is a dice with random value from 1 to 6.
|
dice (:class:`telegram.Dice`, optional): Message is a dice with random value.
|
||||||
via_bot (:class:`telegram.User`, optional): Message was sent through an inline bot.
|
via_bot (:class:`telegram.User`, optional): Bot through which message was sent.
|
||||||
proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`, optional): Service
|
proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`, optional): Service
|
||||||
message. A user in the chat triggered another user's proximity alert while sharing
|
message. A user in the chat triggered another user's proximity alert while sharing
|
||||||
Live Location.
|
Live Location.
|
||||||
|
|
@ -246,7 +246,8 @@ class Message(TelegramObject):
|
||||||
|
|
||||||
.. versionadded:: 20.0
|
.. versionadded:: 20.0
|
||||||
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
|
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:
|
Attributes:
|
||||||
message_id (:obj:`int`): Unique message identifier inside this chat.
|
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
|
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.
|
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
|
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
|
chat. For example, the channel itself for channel posts, the supergroup itself for
|
||||||
non-channel chats, if the message was sent on behalf of a chat.
|
messages from anonymous group administrators, the linked channel for messages
|
||||||
date (:class:`datetime.datetime`): Date the message was sent.
|
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.
|
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
|
forward_from_chat (:class:`telegram.Chat`): Optional. For messages forwarded from channels
|
||||||
or from anonymous administrators, information about the original sender chat.
|
or from anonymous administrators, information about the original sender chat.
|
||||||
forward_from_message_id (:obj:`int`): Optional. Identifier of the original message in the
|
forward_from_message_id (:obj:`int`): Optional. For forwarded channel posts, identifier of
|
||||||
channel.
|
the original message in the channel.
|
||||||
forward_date (:class:`datetime.datetime`): Optional. Date the original message was sent.
|
forward_date (:class:`datetime.datetime`): Optional. For forwarded messages, date the
|
||||||
is_automatic_forward (:obj:`bool`): Optional. :obj:`True`, if the message is a channel post
|
original message was sent in Unix time. Converted to :class:`datetime.datetime`.
|
||||||
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
|
.. versionadded:: 13.9
|
||||||
reply_to_message (:class:`telegram.Message`): Optional. For replies, the original message.
|
reply_to_message (:class:`telegram.Message`): Optional. For replies, the original message.
|
||||||
Note that the Message object in this field will not contain further
|
Note that the Message object in this field will not contain further
|
||||||
``reply_to_message`` fields even if it itself is a reply.
|
``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
|
has_protected_content (:obj:`bool`): Optional. :obj:`True`, if the message can't be
|
||||||
forwarded.
|
forwarded.
|
||||||
|
|
||||||
.. versionadded:: 13.9
|
.. versionadded:: 13.9
|
||||||
media_group_id (:obj:`str`): Optional. The unique identifier of a media message group this
|
media_group_id (:obj:`str`): Optional. The unique identifier of a media message group this
|
||||||
message belongs to.
|
message belongs to.
|
||||||
text (:obj:`str`): Optional. The actual UTF-8 text of the message.
|
text (:obj:`str`): Optional. For text messages, the actual UTF-8 text of the message,
|
||||||
entities (List[:class:`telegram.MessageEntity`]): Special entities like
|
0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters.
|
||||||
usernames, URLs, bot commands, etc. that appear in the text. See
|
entities (List[:class:`telegram.MessageEntity`]): Optional. For text messages, special
|
||||||
:attr:`Message.parse_entity` and :attr:`parse_entities` methods for how to use
|
entities like usernames, URLs, bot commands, etc. that appear in the text. See
|
||||||
properly. This list is empty if the message does not contain entities.
|
:attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly.
|
||||||
caption_entities (List[:class:`telegram.MessageEntity`]): Special entities like
|
This list is empty if the message does not contain entities.
|
||||||
usernames, URLs, bot commands, etc. that appear in the caption. See
|
caption_entities (List[:class:`telegram.MessageEntity`]): Optional. For messages with a
|
||||||
:attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities` methods for how
|
Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the
|
||||||
to use properly. This list is empty if the message does not contain caption entities.
|
caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities`
|
||||||
audio (:class:`telegram.Audio`): Optional. Information about the file.
|
methods for how to use properly. This list is empty if the message does not contain
|
||||||
document (:class:`telegram.Document`): Optional. Information about the file.
|
caption entities.
|
||||||
animation (:class:`telegram.Animation`) Optional. Information about the file.
|
audio (:class:`telegram.Audio`): Optional. Message is an audio file, information
|
||||||
For backward compatibility, when this field is set, the document field will also be
|
about the file.
|
||||||
set.
|
document (:class:`telegram.Document`): Optional. Message is a general file, information
|
||||||
game (:class:`telegram.Game`): Optional. Information about the game.
|
about the file.
|
||||||
photo (List[:class:`telegram.PhotoSize`]): Available sizes of the photo.
|
animation (:class:`telegram.Animation`): Optional. Message is an animation, information
|
||||||
This list is empty if the message does not contain a photo.
|
about the animation. For backward compatibility, when this field is set, the document
|
||||||
sticker (:class:`telegram.Sticker`): Optional. Information about the sticker.
|
field will also be set.
|
||||||
video (:class:`telegram.Video`): Optional. Information about the video.
|
game (:class:`telegram.Game`): Optional. Message is a game, information about the game.
|
||||||
voice (:class:`telegram.Voice`): Optional. Information about the file.
|
photo (List[:class:`telegram.PhotoSize`]): Optional. Message is a photo, available sizes
|
||||||
video_note (:class:`telegram.VideoNote`): Optional. Information about the video message.
|
of the photo. This list is empty if the message does not contain a photo.
|
||||||
new_chat_members (List[:class:`telegram.User`]): Information about new members to
|
sticker (:class:`telegram.Sticker`): Optional. Message is a sticker, information
|
||||||
the chat. The bot itself may be one of these members.
|
about the sticker.
|
||||||
This list is empty if the message does not contain new chat members.
|
video (:class:`telegram.Video`): Optional. Message is a video, information about the
|
||||||
caption (:obj:`str`): Optional. Caption for the document, photo or video,
|
video.
|
||||||
0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH`
|
voice (:class:`telegram.Voice`): Optional. Message is a voice message, information about
|
||||||
characters.
|
the file.
|
||||||
contact (:class:`telegram.Contact`): Optional. Information about the contact.
|
video_note (:class:`telegram.VideoNote`): Optional. Message is a video note, information
|
||||||
location (:class:`telegram.Location`): Optional. Information about the location.
|
about the video message.
|
||||||
venue (:class:`telegram.Venue`): Optional. Information about the venue.
|
new_chat_members (List[:class:`telegram.User`]): Optional. New members that were added to
|
||||||
left_chat_member (:class:`telegram.User`): Optional. Information about the user that left
|
the group or supergroup and information about them (the bot itself may be one of these
|
||||||
the group. (this member may be the bot itself).
|
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_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
|
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.
|
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.
|
delete_chat_photo (:obj:`bool`): Optional. Service message: The chat photo was deleted.
|
||||||
group_chat_created (:obj:`bool`): Optional. The group has been created.
|
group_chat_created (:obj:`bool`): Optional. Service message: The group has been created.
|
||||||
supergroup_chat_created (:obj:`bool`): Optional. The supergroup has been created.
|
supergroup_chat_created (:obj:`bool`): Optional. Service message: The supergroup has been
|
||||||
channel_chat_created (:obj:`bool`): Optional. The channel has been created.
|
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`):
|
message_auto_delete_timer_changed (:class:`telegram.MessageAutoDeleteTimerChanged`):
|
||||||
Optional. Service message: auto-delete timer settings changed in the chat.
|
Optional. Service message: auto-delete timer settings changed in the chat.
|
||||||
|
|
||||||
.. versionadded:: 13.4
|
.. versionadded:: 13.4
|
||||||
migrate_to_chat_id (:obj:`int`): Optional. The group has been migrated to a supergroup with
|
migrate_to_chat_id (:obj:`int`): Optional. The group has been migrated to a supergroup
|
||||||
the specified identifier.
|
with the specified identifier.
|
||||||
migrate_from_chat_id (:obj:`int`): Optional. The supergroup has been migrated from a group
|
migrate_from_chat_id (:obj:`int`): Optional. The supergroup has been migrated from a group
|
||||||
with the specified identifier.
|
with the specified identifier.
|
||||||
pinned_message (:class:`telegram.Message`): Optional. Specified message was pinned.
|
pinned_message (:class:`telegram.Message`): Optional. Specified message was pinned. Note
|
||||||
invoice (:class:`telegram.Invoice`): Optional. Information about the invoice.
|
that the Message object in this field will not contain further
|
||||||
successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Information about the
|
:attr:`reply_to_message` fields even if it is itself a reply.
|
||||||
payment.
|
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
|
connected_website (:obj:`str`): Optional. The domain name of the website on which the user
|
||||||
has logged in.
|
has logged in.
|
||||||
forward_signature (:obj:`str`): Optional. Signature of the post author for messages
|
forward_signature (:obj:`str`): Optional. For messages forwarded from channels, signature
|
||||||
forwarded from channels.
|
of the post author if present.
|
||||||
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.
|
|
||||||
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.
|
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.
|
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,
|
poll (:class:`telegram.Poll`): Optional. Message is a native poll,
|
||||||
information about the poll.
|
information about the poll.
|
||||||
dice (:class:`telegram.Dice`): Optional. Message is a dice.
|
dice (:class:`telegram.Dice`): Optional. Message is a dice with random value.
|
||||||
via_bot (:class:`telegram.User`): Optional. Bot through which the message was sent.
|
via_bot (:class:`telegram.User`): Optional. Bot through which message was sent.
|
||||||
proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`): Optional. Service
|
proximity_alert_triggered (:class:`telegram.ProximityAlertTriggered`): Optional. Service
|
||||||
message. A user in the chat triggered another user's proximity alert while sharing
|
message. A user in the chat triggered another user's proximity alert while sharing
|
||||||
Live Location.
|
Live Location.
|
||||||
|
|
@ -366,7 +398,8 @@ class Message(TelegramObject):
|
||||||
|
|
||||||
.. versionadded:: 20.0
|
.. versionadded:: 20.0
|
||||||
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
|
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
|
.. |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.
|
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.VideoNote`
|
||||||
* :class:`telegram.Voice`
|
* :class:`telegram.Voice`
|
||||||
|
|
||||||
Otherwise :obj:`None` is returned.
|
Otherwise :obj:`None` is returned.
|
||||||
|
|
||||||
.. versionchanged:: 20.0
|
.. versionchanged:: 20.0
|
||||||
:attr:`dice`, :attr:`passport_data` and :attr:`poll` are now also considered to be an
|
: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.
|
in the same way the original message was formatted.
|
||||||
|
|
||||||
Note:
|
Note:
|
||||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||||
Telegram for backward compatibility. You should use :meth:`text_markdown_v2` instead.
|
Telegram for backward compatibility. You should use
|
||||||
|
:meth:`text_markdown_v2` instead.
|
||||||
|
|
||||||
|custom_emoji_formatting_note|
|
* |custom_emoji_formatting_note|
|
||||||
|
|
||||||
Returns:
|
Returns:
|
||||||
:obj:`str`: Message text with entities formatted as Markdown.
|
: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.
|
This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink.
|
||||||
|
|
||||||
Note:
|
Note:
|
||||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||||
Telegram for backward compatibility. You should use :meth:`text_markdown_v2_urled`
|
Telegram for backward compatibility. You should use :meth:`text_markdown_v2_urled`
|
||||||
instead.
|
instead.
|
||||||
|
|
||||||
|custom_emoji_formatting_note|
|
* |custom_emoji_formatting_note|
|
||||||
|
|
||||||
Returns:
|
Returns:
|
||||||
:obj:`str`: Message text with entities formatted as Markdown.
|
: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.
|
Markdown in the same way the original message was formatted.
|
||||||
|
|
||||||
Note:
|
Note:
|
||||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||||
Telegram for backward compatibility. You should use :meth:`caption_markdown_v2`
|
Telegram for backward compatibility. You should use :meth:`caption_markdown_v2`
|
||||||
instead.
|
instead.
|
||||||
|
|
||||||
|custom_emoji_formatting_note|
|
* |custom_emoji_formatting_note|
|
||||||
|
|
||||||
Returns:
|
Returns:
|
||||||
:obj:`str`: Message caption with caption entities formatted as Markdown.
|
: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.
|
Markdown. This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink.
|
||||||
|
|
||||||
Note:
|
Note:
|
||||||
:tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
* :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
|
||||||
Telegram for backward compatibility. You should use :meth:`caption_markdown_v2_urled`
|
Telegram for backward compatibility. You should use
|
||||||
instead.
|
:meth:`caption_markdown_v2_urled` instead.
|
||||||
|
|
||||||
|custom_emoji_formatting_note|
|
* |custom_emoji_formatting_note|
|
||||||
|
|
||||||
Returns:
|
Returns:
|
||||||
:obj:`str`: Message caption with caption entities formatted as Markdown.
|
:obj:`str`: Message caption with caption entities formatted as Markdown.
|
||||||
|
|
|
||||||
|
|
@ -63,13 +63,26 @@ class MessageEntity(TelegramObject):
|
||||||
|
|
||||||
.. versionadded:: 20.0
|
.. versionadded:: 20.0
|
||||||
Attributes:
|
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.
|
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.
|
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.
|
user (:class:`telegram.User`): Optional. The mentioned user.
|
||||||
language (:obj:`str`): Optional. Programming language of the entity text.
|
language (:obj:`str`): Optional. For :attr:`PRE` only, The programming language of
|
||||||
custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji.
|
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
|
.. 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
|
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.
|
considered equal, if their :attr:`label` and :attr:`amount` are equal.
|
||||||
|
|
||||||
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
|
Examples:
|
||||||
|
:any:`Payment Bot <examples.paymentbot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
label (:obj:`str`): Portion label.
|
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
|
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||||
considered equal, if their :attr:`id` is equal.
|
considered equal, if their :attr:`id` is equal.
|
||||||
|
|
||||||
.. seealso:: `Paymentbot Example <examples.paymentbot.html>`_
|
Examples:
|
||||||
|
:any:`Payment Bot <examples.paymentbot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
id (:obj:`str`): Shipping option identifier.
|
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
|
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||||
considered equal, if their :attr:`id` is equal.
|
considered equal, if their :attr:`id` is equal.
|
||||||
|
|
||||||
.. seealso:: `Pollbot Example <examples.pollbot.html>`_
|
Examples:
|
||||||
|
:any:`Poll Bot <examples.pollbot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
id (:obj:`str`): Unique poll identifier.
|
id (:obj:`str`): Unique poll identifier.
|
||||||
|
|
@ -126,13 +127,17 @@ class Poll(TelegramObject):
|
||||||
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
|
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
|
||||||
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
|
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.
|
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.
|
correct_option_id (:obj:`int`, optional): A zero based identifier of the correct answer
|
||||||
Available only for polls in the quiz mode, which are closed, or was sent (not
|
option. Available only for closed polls in the quiz mode, which were sent
|
||||||
forwarded) by the bot or to the private chat with the bot.
|
(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
|
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.
|
answer or taps on the lamp icon in a quiz-style poll, 0-200 characters.
|
||||||
explanation_entities (List[:class:`telegram.MessageEntity`], optional): Special entities
|
explanation_entities (List[:class:`telegram.MessageEntity`], optional): Special entities
|
||||||
like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
|
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
|
open_period (:obj:`int`, optional): Amount of time in seconds the poll will be active
|
||||||
after creation.
|
after creation.
|
||||||
close_date (:obj:`datetime.datetime`, optional): Point in time (Unix timestamp) when the
|
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.
|
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
|
||||||
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
|
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.
|
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
|
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
|
explanation_entities (List[:class:`telegram.MessageEntity`]): Special entities
|
||||||
like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
|
like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
|
||||||
This list is empty if the message does not contain explanation entities.
|
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
|
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.
|
considered equal, if their size of :attr:`keyboard` and all the buttons are equal.
|
||||||
|
|
||||||
Example:
|
Examples:
|
||||||
A user requests to change the bot's language, bot replies to the request with a keyboard
|
* Example usage: A user requests to change the bot's language, bot replies to the request
|
||||||
to select the new language. Other users in the group don't see the keyboard.
|
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:
|
Args:
|
||||||
keyboard (List[List[:obj:`str` | :class:`telegram.KeyboardButton`]]): Array of button rows,
|
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
|
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`).
|
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:
|
Note:
|
||||||
User will not be able to summon this keyboard; if you want to hide the keyboard from
|
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`.
|
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:
|
Args:
|
||||||
selective (:obj:`bool`, optional): Use this parameter if you want to remove the keyboard
|
selective (:obj:`bool`, optional): Use this parameter if you want to remove the keyboard
|
||||||
for specific users only. Targets:
|
for specific users only. Targets:
|
||||||
|
|
|
||||||
|
|
@ -37,20 +37,12 @@ Tele_co = TypeVar("Tele_co", bound="TelegramObject", covariant=True)
|
||||||
class TelegramObject:
|
class TelegramObject:
|
||||||
"""Base class for most Telegram objects.
|
"""Base class for most Telegram objects.
|
||||||
|
|
||||||
Objects of this type are subscriptable with strings, where ``telegram_object[attribute_name]``
|
Objects of this type are subscriptable with strings. See :meth:`__getitem__` for more details.
|
||||||
is equivalent to ``telegram_object.attribute_name``. If the object does not have an attribute
|
The :mod:`pickle` and :func:`~copy.deepcopy` behavior of objects of this type are defined by
|
||||||
with the appropriate name, a :exc:`KeyError` will be raised.
|
:meth:`__getstate__`, :meth:`__setstate__` and :meth:`__deepcopy__`.
|
||||||
|
|
||||||
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()
|
|
||||||
|
|
||||||
.. versionchanged:: 20.0
|
.. 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
|
* Removed argument and attribute ``bot`` for several subclasses. Use
|
||||||
:meth:`set_bot` and :meth:`get_bot` instead.
|
:meth:`set_bot` and :meth:`get_bot` instead.
|
||||||
* Removed the possibility to pass arbitrary keyword arguments for several subclasses.
|
* Removed the possibility to pass arbitrary keyword arguments for several subclasses.
|
||||||
|
|
@ -108,7 +100,7 @@ class TelegramObject:
|
||||||
def __repr__(self) -> str:
|
def __repr__(self) -> str:
|
||||||
"""Gives a string representation of this object in the form
|
"""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
|
``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.).
|
:class:`list`, :class:`dict`, :class:`set`, :class:`str`, etc.).
|
||||||
|
|
||||||
As this class doesn't implement :meth:`object.__str__`, the default implementation
|
As this class doesn't implement :meth:`object.__str__`, the default implementation
|
||||||
|
|
@ -141,6 +133,30 @@ class TelegramObject:
|
||||||
return f"{self.__class__.__name__}({contents})"
|
return f"{self.__class__.__name__}({contents})"
|
||||||
|
|
||||||
def __getitem__(self, item: str) -> object:
|
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":
|
if item == "from":
|
||||||
item = "from_user"
|
item = "from_user"
|
||||||
try:
|
try:
|
||||||
|
|
@ -153,15 +169,28 @@ class TelegramObject:
|
||||||
|
|
||||||
def __getstate__(self) -> Dict[str, Union[str, object]]:
|
def __getstate__(self) -> Dict[str, Union[str, object]]:
|
||||||
"""
|
"""
|
||||||
This method is used for pickling. We remove the bot attribute of the object since those
|
Overrides :meth:`object.__getstate__` to customize the pickling process of objects of this
|
||||||
are not pickable.
|
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)
|
return self._get_attrs(include_private=True, recursive=False, remove_bot=True)
|
||||||
|
|
||||||
def __setstate__(self, state: dict) -> None:
|
def __setstate__(self, state: dict) -> None:
|
||||||
"""
|
"""
|
||||||
This method is used for unpickling. The data, which is in the form a dictionary, is
|
Overrides :meth:`object.__setstate__` to customize the unpickling process of objects of
|
||||||
converted back into a class. Should be modified in place.
|
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
|
# Make sure that we have a `_bot` attribute. This is necessary, since __getstate__ omits
|
||||||
# this as Bots are not pickable.
|
# this as Bots are not pickable.
|
||||||
|
|
@ -172,7 +201,20 @@ class TelegramObject:
|
||||||
self._apply_api_kwargs()
|
self._apply_api_kwargs()
|
||||||
|
|
||||||
def __deepcopy__(self: Tele_co, memodict: dict) -> Tele_co:
|
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
|
bot = self._bot # Save bot so we can set it after copying
|
||||||
self.set_bot(None) # set to None so it is not deepcopied
|
self.set_bot(None) # set to None so it is not deepcopied
|
||||||
cls = self.__class__
|
cls = self.__class__
|
||||||
|
|
@ -387,6 +429,26 @@ class TelegramObject:
|
||||||
self._bot = bot
|
self._bot = bot
|
||||||
|
|
||||||
def __eq__(self, other: object) -> bool:
|
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 isinstance(other, self.__class__):
|
||||||
if not self._id_attrs:
|
if not self._id_attrs:
|
||||||
warn(
|
warn(
|
||||||
|
|
@ -404,6 +466,12 @@ class TelegramObject:
|
||||||
return super().__eq__(other)
|
return super().__eq__(other)
|
||||||
|
|
||||||
def __hash__(self) -> int:
|
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:
|
if self._id_attrs:
|
||||||
return hash((self.__class__, self._id_attrs))
|
return hash((self.__class__, self._id_attrs))
|
||||||
return super().__hash__()
|
return super().__hash__()
|
||||||
|
|
|
||||||
|
|
@ -46,6 +46,9 @@ class Update(TelegramObject):
|
||||||
Note:
|
Note:
|
||||||
At most one of the optional parameters can be present in any given update.
|
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:
|
Args:
|
||||||
update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a
|
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
|
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
|
chosen_inline_result (:class:`telegram.ChosenInlineResult`): Optional. The result of an
|
||||||
inline query that was chosen by a user.
|
inline query that was chosen by a user.
|
||||||
callback_query (:class:`telegram.CallbackQuery`): Optional. New incoming callback query.
|
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.
|
shipping_query (:class:`telegram.ShippingQuery`): Optional. New incoming shipping query.
|
||||||
pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming
|
pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming
|
||||||
pre-checkout query.
|
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
|
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.
|
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
|
.. versionadded:: 20.0
|
||||||
|
|
||||||
|
|
@ -45,8 +46,7 @@ class WebAppData(TelegramObject):
|
||||||
button, from which the Web App was opened.
|
button, from which the Web App was opened.
|
||||||
|
|
||||||
Warning:
|
Warning:
|
||||||
Be aware that a bad client can send
|
Be aware that a bad client can send arbitrary data in this field.
|
||||||
arbitrary data in this field.
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
__slots__ = ("data", "button_text")
|
__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
|
Objects of this class are comparable in terms of equality. Two objects of this class are
|
||||||
considered equal, if their :attr:`url` are equal.
|
considered equal, if their :attr:`url` are equal.
|
||||||
|
|
||||||
.. seealso:: `Webappbot Example <examples.webappbot.html>`_
|
Examples:
|
||||||
|
:any:`Webapp Bot <examples.webappbot>`
|
||||||
|
|
||||||
.. versionadded:: 20.0
|
.. versionadded:: 20.0
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -62,14 +62,17 @@ class WebhookInfo(TelegramObject):
|
||||||
|
|
||||||
.. versionadded:: 20.0
|
.. versionadded:: 20.0
|
||||||
Attributes:
|
Attributes:
|
||||||
url (:obj:`str`): Webhook URL.
|
url (:obj:`str`): Webhook URL, may be empty if webhook is not set up.
|
||||||
has_custom_certificate (:obj:`bool`): If a custom certificate was provided for webhook.
|
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.
|
pending_update_count (:obj:`int`): Number of updates awaiting delivery.
|
||||||
ip_address (:obj:`str`): Optional. Currently used webhook IP address.
|
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_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.
|
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
|
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
|
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`.
|
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
|
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):
|
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",)
|
__slots__ = ("message",)
|
||||||
|
|
||||||
|
|
@ -84,6 +89,9 @@ class TelegramError(Exception):
|
||||||
class Forbidden(TelegramError):
|
class Forbidden(TelegramError):
|
||||||
"""Raised when the bot has not enough rights to perform the requested action.
|
"""Raised when the bot has not enough rights to perform the requested action.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
:any:`Raw API Bot <examples.rawapibot>`
|
||||||
|
|
||||||
.. versionchanged:: 20.0
|
.. versionchanged:: 20.0
|
||||||
This class was previously named ``Unauthorized``.
|
This class was previously named ``Unauthorized``.
|
||||||
"""
|
"""
|
||||||
|
|
@ -107,7 +115,11 @@ class InvalidToken(TelegramError):
|
||||||
|
|
||||||
|
|
||||||
class NetworkError(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__ = ()
|
__slots__ = ()
|
||||||
|
|
||||||
|
|
@ -137,6 +149,10 @@ class ChatMigrated(TelegramError):
|
||||||
"""
|
"""
|
||||||
Raised when the requested group chat migrated to supergroup and has a new chat id.
|
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:
|
Args:
|
||||||
new_chat_id (:obj:`int`): The new chat id of the group.
|
new_chat_id (:obj:`int`): The new chat id of the group.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -51,7 +51,7 @@ else:
|
||||||
class AIORateLimiter(BaseRateLimiter[int]):
|
class AIORateLimiter(BaseRateLimiter[int]):
|
||||||
"""
|
"""
|
||||||
Implementation of :class:`~telegram.ext.BaseRateLimiter` using the library
|
Implementation of :class:`~telegram.ext.BaseRateLimiter` using the library
|
||||||
`aiolimiter <https://aiolimiter.readthedocs.io/>`_.
|
`aiolimiter <https://aiolimiter.readthedocs.io/en/stable>`_.
|
||||||
|
|
||||||
Important:
|
Important:
|
||||||
If you want to use this class, you must install PTB with the optional requirement
|
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`.
|
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.
|
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
|
.. versionadded:: 20.0
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
|
|
|
||||||
|
|
@ -133,6 +133,14 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
||||||
finally:
|
finally:
|
||||||
await application.shutdown()
|
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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* Initialization is now done through the :class:`telegram.ext.ApplicationBuilder`.
|
* 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`
|
job_queue (:class:`telegram.ext.JobQueue`): Optional. The :class:`telegram.ext.JobQueue`
|
||||||
instance to pass onto handler callbacks.
|
instance to pass onto handler callbacks.
|
||||||
chat_data (:obj:`types.MappingProxyType`): A dictionary handlers can use to store data for
|
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
|
.. 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::
|
.. tip::
|
||||||
Manually modifying :attr:`chat_data` is almost never needed and unadvisable.
|
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
|
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
|
.. 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::
|
.. tip::
|
||||||
Manually modifying :attr:`user_data` is almost never needed and unadvisable.
|
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:
|
def concurrent_updates(self) -> int:
|
||||||
""":obj:`int`: The number of concurrent updates that will be processed in parallel. A
|
""":obj:`int`: The number of concurrent updates that will be processed in parallel. A
|
||||||
value of ``0`` indicates updates are *not* being processed concurrently.
|
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
|
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`
|
If :attr:`post_shutdown` is set, it will be called after both :meth:`shutdown`
|
||||||
and :meth:`telegram.ext.Updater.shutdown`.
|
and :meth:`telegram.ext.Updater.shutdown`.
|
||||||
|
|
||||||
|
.. include:: inclusions/application_run_tip.rst
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
:meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown`
|
: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:
|
Args:
|
||||||
poll_interval (:obj:`float`, optional): Time to wait between polling updates from
|
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,
|
secret_token: str = None,
|
||||||
) -> None:
|
) -> None:
|
||||||
"""Convenience method that takes care of initializing and starting the app,
|
"""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.
|
a graceful shutdown of the app on exit.
|
||||||
|
|
||||||
The app will shut down when :exc:`KeyboardInterrupt` or :exc:`SystemExit` is raised.
|
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]
|
pip install python-telegram-bot[webhooks]
|
||||||
|
|
||||||
|
.. include:: inclusions/application_run_tip.rst
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
:meth:`initialize`, :meth:`start`, :meth:`stop`, :meth:`shutdown`
|
: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:
|
Args:
|
||||||
listen (:obj:`str`, optional): IP-Address to listen on. Defaults to
|
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
|
* If the application is currently running, tasks created by this method will be
|
||||||
awaited with :meth:`stop`.
|
awaited with :meth:`stop`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
coroutine (:term:`coroutine function`): The coroutine to run as task.
|
coroutine (:term:`coroutine function`): The coroutine to run as task.
|
||||||
update (:obj:`object`, optional): If set, will be passed to :meth:`process_error`
|
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.
|
"""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`.
|
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
|
.. versionchanged:: 20.0
|
||||||
Persistence is now updated in an interval set by
|
Persistence is now updated in an interval set by
|
||||||
:attr:`telegram.ext.BasePersistence.update_interval`.
|
: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
|
to the asynchronous nature of these features. Please make sure that your program can
|
||||||
avoid or handle such situations.
|
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:
|
Args:
|
||||||
message (:class:`telegram.Message`, optional): A message with either
|
message (:class:`telegram.Message`, optional): A message with either
|
||||||
:attr:`~telegram.Message.migrate_from_chat_id` or
|
:attr:`~telegram.Message.migrate_from_chat_id` or
|
||||||
|
|
@ -1423,7 +1459,11 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
|
||||||
Note:
|
Note:
|
||||||
Attempts to add the same callback multiple times will be ignored.
|
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:
|
Args:
|
||||||
callback (:term:`coroutine function`): The callback function for this error handler.
|
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
|
* Unless a custom :class:`telegram.Bot` instance is set via :meth:`bot`, :meth:`build` will
|
||||||
use :class:`telegram.ext.ExtBot` for the bot.
|
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
|
.. _`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]
|
pip install python-telegram-bot[callback-data]
|
||||||
|
|
||||||
.. seealso:: `Arbitrary callback_data <https://github.com/python-telegram-bot\
|
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||||
/python-telegram-bot/wiki/Arbitrary-callback_data>`_,
|
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_,
|
||||||
:any:`examples.arbitrarycallbackdatabot`
|
:any:`examples.arbitrarycallbackdatabot`
|
||||||
|
|
||||||
Args:
|
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
|
type of the argument of :meth:`refresh_bot_data` and the return value of
|
||||||
:meth:`get_bot_data`.
|
: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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
* The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
||||||
|
|
|
||||||
|
|
@ -37,6 +37,11 @@ class BaseRateLimiter(ABC, Generic[RLARGS]):
|
||||||
Hint:
|
Hint:
|
||||||
Requests to :meth:`~telegram.Bot.get_updates` are never rate limited.
|
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
|
.. 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`).
|
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`).
|
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:
|
Args:
|
||||||
application (:class:`telegram.ext.Application`): The application associated with this
|
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:
|
def bot_data(self) -> BD:
|
||||||
""":obj:`ContextTypes.bot_data`: Optional. An object that can be used to keep any data in.
|
""":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`.
|
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
|
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/
|
<https://github.com/python-telegram-bot/python-telegram-bot/wiki/
|
||||||
Storing-bot,-user-and-chat-related-data#chat-migration>`_.
|
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
|
.. versionchanged:: 20.0
|
||||||
The chat data is now also present in error handlers if the error is caused by a job.
|
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`.
|
For each update from the same user it will be the same :obj:`ContextTypes.user_data`.
|
||||||
Defaults to :obj:`dict`.
|
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
|
.. versionchanged:: 20.0
|
||||||
The user data is now also present in error handlers if the error is caused by a job.
|
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 *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.
|
*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:
|
Args:
|
||||||
callback_query (:class:`telegram.CallbackQuery`): The callback query.
|
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.JobQueue`: The :class:`JobQueue` used by the
|
||||||
:class:`telegram.ext.Application`.
|
: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
|
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.
|
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
|
.. versionadded:: 13.6
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
|
|
@ -93,8 +99,8 @@ class CallbackDataCache:
|
||||||
"""A custom cache for storing the callback data of a :class:`telegram.ext.ExtBot`. Internally,
|
"""A custom cache for storing the callback data of a :class:`telegram.ext.ExtBot`. Internally,
|
||||||
it keeps two mappings with fixed maximum size:
|
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 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 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
|
The second mapping allows to manually drop data that has been cached for keyboards of messages
|
||||||
sent via inline mode.
|
sent via inline mode.
|
||||||
|
|
@ -108,10 +114,14 @@ class CallbackDataCache:
|
||||||
|
|
||||||
pip install python-telegram-bot[callback-data]
|
pip install python-telegram-bot[callback-data]
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||||
|
|
||||||
.. seealso:: :attr:`telegram.ext.ExtBot.callback_data_cache`,
|
.. seealso:: :attr:`telegram.ext.ExtBot.callback_data_cache`,
|
||||||
`Arbitrary callback_data <https://github.com/python-telegram-bot/
|
`Architecture Overview <https://github.com/\
|
||||||
python-telegram-bot/wiki/Arbitrary-callback_data>`_,
|
python-telegram-bot/python-telegram-bot/wiki/Architecture>`_,
|
||||||
Arbitrary Callback Data Example <examples.arbitrarycallbackdatabot.html>
|
`Arbitrary callback_data <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||||
|
|
||||||
.. versionadded:: 13.6
|
.. versionadded:: 13.6
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -81,12 +81,18 @@ class CallbackQueryHandler(BaseHandler[Update, CCT]):
|
||||||
If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the
|
If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the
|
||||||
:class:`telegram.CallbackQuery` update will not be handled.
|
: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
|
.. versionchanged:: 13.6
|
||||||
Added support for arbitrary callback data.
|
Added support for arbitrary callback data.
|
||||||
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
||||||
be awaited before processing the next handler in
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
pattern (:func:`re.Pattern <re.compile>` | :obj:`callable` | :obj:`type`): Optional.
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
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
|
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.
|
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
|
.. versionadded:: 13.4
|
||||||
|
|
||||||
|
|
@ -56,6 +57,9 @@ class ChatMemberHandler(BaseHandler[Update, CCT]):
|
||||||
be awaited before processing the next handler in
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
chat_member_types (:obj:`int`, optional): Specifies if this handler should handle
|
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
|
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
||||||
be awaited before processing the next handler in
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
: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
|
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Regex pattern. If not
|
||||||
:obj:`None`, :func:`re.match`
|
:obj:`None`, :func:`re.match`
|
||||||
is used on :attr:`telegram.ChosenInlineResult.result_id` to determine if an update
|
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
|
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.
|
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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* Renamed the attribute ``command`` to :attr:`commands`, which now is always a
|
* 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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Raises:
|
Raises:
|
||||||
:exc:`ValueError`: When the command is too long or has illegal chars.
|
: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`
|
Convenience class to gather customizable types of the :class:`telegram.ext.CallbackContext`
|
||||||
interface.
|
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
|
.. versionadded:: 13.6
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -185,10 +185,11 @@ class ConversationHandler(BaseHandler[Update, CCT]):
|
||||||
conversation. For an example on nested :class:`ConversationHandler` s, see
|
conversation. For an example on nested :class:`ConversationHandler` s, see
|
||||||
:any:`examples.nestedconversationbot`.
|
:any:`examples.nestedconversationbot`.
|
||||||
|
|
||||||
.. seealso:: `Conversation Example <examples.conversationbot.html>`_,
|
Examples:
|
||||||
`Conversation Example 2 <examples.conversationbot2.html>`_,
|
* :any:`Conversation Bot <examples.conversationbot>`
|
||||||
`Nested Conversation Example <examples.nestedconversationbot.html>`_,
|
* :any:`Conversation Bot 2 <examples.conversationbot2>`
|
||||||
`Persistent Conversation Example <examples.persistentconversationbot.html>`_
|
* :any:`Nested Conversation Bot <examples.nestedconversationbot>`
|
||||||
|
* :any:`Persistent Conversation Bot <examples.persistentconversationbot>`
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
entry_points (List[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler`
|
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)
|
2. the value passed to this parameter (if any)
|
||||||
3. :attr:`telegram.ext.Defaults.block` (if defaults are used)
|
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
|
.. versionchanged:: 20.0
|
||||||
No longer overrides the handlers settings. Resolution order was changed.
|
No longer overrides the handlers settings. Resolution order was changed.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -26,6 +26,11 @@ from telegram._utils.datetime import UTC
|
||||||
class Defaults:
|
class Defaults:
|
||||||
"""Convenience Class to gather all parameters with a (user defined) default value
|
"""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
|
.. versionchanged:: 20.0
|
||||||
Removed the argument and attribute ``timeout``. Specify default timeout behavior for the
|
Removed the argument and attribute ``timeout``. Specify default timeout behavior for the
|
||||||
networking backend directly via :class:`telegram.ext.ApplicationBuilder` instead.
|
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
|
* This implementation of :class:`BasePersistence` does not handle data that cannot be
|
||||||
serialized by :func:`json.dumps`.
|
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
|
.. versionchanged:: 20.0
|
||||||
The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
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
|
* 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.
|
additional argument, as this method will never be rate limited.
|
||||||
|
|
||||||
.. seealso:: `Arbitrary Callback Example <examples.arbitrarycallbackdatabot.html>`_,
|
Examples:
|
||||||
`Arbitrary callback_data <https://github.com/python-telegram-bot/
|
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||||
python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
|
||||||
|
.. seealso:: `Arbitrary callback_data <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
|
||||||
|
|
||||||
.. versionadded:: 13.6
|
.. versionadded:: 13.6
|
||||||
|
|
||||||
|
|
@ -134,9 +136,11 @@ class ExtBot(Bot, Generic[RLARGS]):
|
||||||
be used if not set explicitly in the bot methods.
|
be used if not set explicitly in the bot methods.
|
||||||
arbitrary_callback_data (:obj:`bool` | :obj:`int`, optional): Whether to
|
arbitrary_callback_data (:obj:`bool` | :obj:`int`, optional): Whether to
|
||||||
allow arbitrary objects as callback data for :class:`telegram.InlineKeyboardButton`.
|
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
|
Pass an integer to specify the maximum number of objects cached in memory.
|
||||||
details, please see our `wiki <https://github.com/python-telegram-bot\
|
Defaults to :obj:`False`.
|
||||||
/python-telegram-bot/wiki/Arbitrary-callback_data>`_. 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
|
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.
|
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
|
""":class:`telegram.ext.CallbackDataCache`: Optional. The cache for
|
||||||
objects passed as callback data for :class:`telegram.InlineKeyboardButton`.
|
objects passed as callback data for :class:`telegram.InlineKeyboardButton`.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
:any:`Arbitrary Callback Data Bot <examples.arbitrarycallbackdatabot>`
|
||||||
|
|
||||||
.. versionchanged:: 20.0
|
.. versionchanged:: 20.0
|
||||||
* This property is now read-only.
|
* This property is now read-only.
|
||||||
* This property is now optional and can be :obj:`None` if
|
* 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
|
also used for the mentioned method arguments. That way, a type checker can check whether
|
||||||
this handler fits the definition of the :class:`~Application`.
|
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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* The attribute ``run_async`` is now :paramref:`block`.
|
* 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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
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
|
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.
|
updates won't be handled, if :attr:`chat_types` is passed.
|
||||||
|
|
||||||
.. seealso:: `Inlinebot Example <examples.inlinebot.html>`_
|
Examples:
|
||||||
|
:any:`Inline Bot <examples.inlinebot>`
|
||||||
|
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
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
|
block (:obj:`bool`, optional): Determines whether the return value of the callback should
|
||||||
be awaited before processing the next handler in
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
: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
|
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`.
|
handle inline queries with the appropriate :attr:`telegram.InlineQuery.chat_type`.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -53,9 +53,13 @@ class JobQueue:
|
||||||
|
|
||||||
pip install python-telegram-bot[job-queue]
|
pip install python-telegram-bot[job-queue]
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
:any:`Timer Bot <examples.timerbot>`
|
||||||
|
|
||||||
.. seealso:: :attr:`telegram.ext.Application.job_queue`,
|
.. seealso:: :attr:`telegram.ext.Application.job_queue`,
|
||||||
:attr:`telegram.ext.CallbackContext.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/
|
`Job Queue <https://github.com/python-telegram-bot/
|
||||||
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
|
python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`_
|
||||||
|
|
||||||
|
|
@ -639,6 +643,9 @@ class Job:
|
||||||
This class should not be instantiated manually.
|
This class should not be instantiated manually.
|
||||||
Use the methods of :class:`telegram.ext.JobQueue` to schedule jobs.
|
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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* Removed argument and attribute ``job_queue``.
|
* 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`.
|
: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
|
If you don't want or need any of those pass ``~filters.UpdateType.*`` in the filter
|
||||||
argument.
|
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
|
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
|
called when :meth:`check_update` has determined that an update should be processed by
|
||||||
this handler. Callback signature::
|
this handler. Callback signature::
|
||||||
|
|
@ -61,6 +64,9 @@ class MessageHandler(BaseHandler[Update, CCT]):
|
||||||
be awaited before processing the next handler in
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
filters (:class:`telegram.ext.filters.BaseFilter`): Only allow updates with these Filters.
|
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.
|
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 replaced by a placeholder before pickling and
|
||||||
:attr:`~BasePersistence.bot` will be inserted back when loading the data.
|
: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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* The parameters and attributes ``store_*_data`` were replaced by :attr:`store_data`.
|
* 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
|
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.
|
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:
|
Args:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
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
|
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.
|
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:
|
Args:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
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
|
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.
|
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:
|
Args:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
commands (FrozenSet[:obj:`str`]): The commands that this handler will listen for, i.e. the
|
commands (FrozenSet[:obj:`str`]): The commands that this handler will listen for, i.e. the
|
||||||
combinations of :paramref:`prefix` and :paramref:`command`.
|
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
|
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.
|
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:
|
Args:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler. Will be
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
callback (:term:`coroutine function`): The callback function for this handler.
|
||||||
block (:obj:`bool`): Determines whether the callback will run in a blocking way..
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
command (:obj:`str`): The command this handler should listen for.
|
command (:obj:`str`): The command this handler should listen for.
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
|
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
|
||||||
callback (:term:`coroutine function`): The callback function for this handler.
|
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
|
be awaited before processing the next handler in
|
||||||
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
:meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
|
||||||
|
|
||||||
|
.. seealso:: `Concurrency <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
|
||||||
|
|
||||||
Attributes:
|
Attributes:
|
||||||
type (:external:class:`type`): The :external:class:`type` of updates this handler should
|
type (:external:class:`type`): The :external:class:`type` of updates this handler should
|
||||||
process.
|
process.
|
||||||
|
|
|
||||||
|
|
@ -65,6 +65,11 @@ class Updater(AbstractAsyncContextManager):
|
||||||
finally:
|
finally:
|
||||||
await updater.shutdown()
|
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
|
.. versionchanged:: 20.0
|
||||||
|
|
||||||
* Removed argument and attribute ``user_sig_handler``
|
* Removed argument and attribute ``user_sig_handler``
|
||||||
|
|
@ -392,6 +397,9 @@ class Updater(AbstractAsyncContextManager):
|
||||||
|
|
||||||
pip install python-telegram-bot[webhooks]
|
pip install python-telegram-bot[webhooks]
|
||||||
|
|
||||||
|
.. seealso:: `Webhooks <https://github.com/\
|
||||||
|
python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_
|
||||||
|
|
||||||
.. versionchanged:: 13.4
|
.. versionchanged:: 13.4
|
||||||
:meth:`start_webhook` now *always* calls :meth:`telegram.Bot.set_webhook`, so pass
|
: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.
|
``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.
|
:mod:`~telegram.ext.filters` module.
|
||||||
#. The names of all filters has been updated:
|
#. The names of all filters has been updated:
|
||||||
|
|
||||||
* Filter classes which are ready for use, e.g ``Filters.all`` are now capitalized, e.g
|
* Filter classes which are ready for use, e.g ``Filters.all`` are now capitalized, e.g
|
||||||
``filters.ALL``.
|
``filters.ALL``.
|
||||||
* Filters which need to be initialized are now in CamelCase. E.g. ``filters.User(...)``.
|
* 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 which do both (like ``Filters.text``) are now split as ready-to-use version
|
||||||
``filters.TEXT`` and class version ``filters.Text(...)``.
|
``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.
|
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:
|
Attributes:
|
||||||
name (:obj:`str`): Name for this filter. Defaults to the type of filter.
|
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
|
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
|
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.
|
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:
|
Args:
|
||||||
pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
|
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:
|
def mention_html(user_id: Union[int, str], name: str) -> str:
|
||||||
"""
|
"""
|
||||||
|
Helper function to create a user mention as HTML tag.
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
user_id (:obj:`int`): The user's id which you want to mention.
|
user_id (:obj:`int`): The user's id which you want to mention.
|
||||||
name (:obj:`str`): The name the mention is showing.
|
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:
|
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:
|
Args:
|
||||||
user_id (:obj:`int`): The user's id which you want to mention.
|
user_id (:obj:`int`): The user's id which you want to mention.
|
||||||
name (:obj:`str`): The name the mention is showing.
|
name (:obj:`str`): The name the mention is showing.
|
||||||
|
|
@ -110,7 +114,7 @@ def effective_message_type(entity: Union["Message", "Update"]) -> Optional[str]:
|
||||||
|
|
||||||
Returns:
|
Returns:
|
||||||
:obj:`str` | :obj:`None`: One of :class:`telegram.constants.MessageType` if the entity
|
: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
|
# 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'))``
|
``CommandHandler("start", callback, filters=filters.Regex('payload'))``
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
``create_deep_linked_url(bot.get_me().username, "some-params")``
|
* ``create_deep_linked_url(bot.get_me().username, "some-params")``
|
||||||
|
* :any:`Deep Linking <examples.deeplinking>`
|
||||||
.. seealso:: `Deeplinking Example <examples.deeplinking.html>`_
|
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
bot_username (:obj:`str`): The username to link to
|
bot_username (:obj:`str`): The username to link to.
|
||||||
payload (:obj:`str`, optional): Parameters to encode in the created URL
|
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
|
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.
|
add the bot to. If :obj:`False`, opens a one-on-one conversation with the bot.
|
||||||
Defaults to :obj:`False`.
|
Defaults to :obj:`False`.
|
||||||
|
|
||||||
Returns:
|
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:
|
if bot_username is None or len(bot_username) <= 3:
|
||||||
raise ValueError("You must provide a valid bot_username.")
|
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
|
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`.
|
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
|
.. versionadded:: 20.0
|
||||||
"""
|
"""
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -28,6 +28,9 @@ class PTBUserWarning(UserWarning):
|
||||||
"""
|
"""
|
||||||
Custom user warning class used for warnings in this library.
|
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
|
.. versionadded:: 20.0
|
||||||
"""
|
"""
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue