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

Documentation Improvements (#3010, #3007, #3012, #3067, #3081, #3082)

Browse source 
Co-authored-by: KnorpelSenf <shtrog@gmail.com>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
Co-authored-by: Poolitzer <github@poolitzer.eu>
Co-authored-by: Adi <71205439+Aditya-Rajgor@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2022-06-09 17:08:54 +02:00 committed by GitHub
parent d6e95f1974
commit 11007c1715
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
35 changed files with 362 additions and 477 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
.github/CONTRIBUTING.rst vendored
View file

@ -263,19 +263,19 @@ break the API classes. For example:
self.last_name = last_name self.last_name = last_name
.. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/ .. _`Code of Conduct`: https://www.python.org/psf/conduct/
.. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues .. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues
.. _`Telegram group`: https://telegram.me/pythontelegrambotgroup .. _`Telegram group`: https://telegram.me/pythontelegrambotgroup
.. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/ .. _`PEP 8 Style Guide`: https://peps.python.org/pep-0008/
.. _`sphinx`: http://sphinx-doc.org .. _`sphinx`: https://www.sphinx-doc.org/en/master
.. _`Google Python Style Guide`: http://google.github.io/styleguide/pyguide.html .. _`Google Python Style Guide`: https://google.github.io/styleguide/pyguide.html
.. _`Google Python Style Docstrings`: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html .. _`Google Python Style Docstrings`: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
.. _AUTHORS.rst: ../AUTHORS.rst .. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst
.. _`MyPy`: https://mypy.readthedocs.io/en/stable/index.html .. _`MyPy`: https://mypy.readthedocs.io/en/stable/index.html
.. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
.. _`Black`: https://black.readthedocs.io/en/stable/index.html .. _`Black`: https://black.readthedocs.io/en/stable/index.html
.. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html .. _`popular editors`: https://black.readthedocs.io/en/stable/integrations/editors.html
.. _`RTD`: https://python-telegram-bot.readthedocs.io/ .. _`RTD`: https://docs.python-telegram-bot.org/
.. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes .. _`RTD build`: https://docs.python-telegram-bot.org/en/doc-fixes
.. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html .. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html
.. _`section`: #documenting .. _`section`: #documenting

29
.github/workflows/docs-linkcheck.yml vendored Normal file
View file

@ -0,0 +1,29 @@
name: Check Links in Documentation
on:
schedule:
# First day of month at 05:46 in every 2nd month
- cron: '46 5 1 */2 *'
jobs:
test-sphinx-build:
name: test-sphinx-linkcheck
runs-on: ${{matrix.os}}
strategy:
matrix:
python-version: [3.7]
os: [ubuntu-latest]
fail-fast: False
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v3
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -W ignore -m pip install --upgrade pip
python -W ignore -m pip install -r requirements.txt
python -W ignore -m pip install -r requirements-dev.txt
python -W ignore -m pip install -r docs/requirements-docs.txt
- name: Check Links
run: sphinx-build docs/source docs/build/html -W --keep-going -j auto -b linkcheck

5
.github/workflows/docs.yml vendored
View file

@ -3,12 +3,10 @@ on:
pull_request: pull_request:
branches: branches:
- master - master
- v14
- doc-fixes - doc-fixes
push: push:
branches: branches:
- master - master
- v14
- doc-fixes - doc-fixes
jobs: jobs:
@ -22,9 +20,6 @@ jobs:
fail-fast: False fail-fast: False
steps: steps:
- uses: actions/checkout@v3 - uses: actions/checkout@v3
- name: Initialize vendored libs
run:
git submodule update --init --recursive
- name: Set up Python ${{ matrix.python-version }} - name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v3 uses: actions/setup-python@v3
with: with:

6
.readthedocs.yml
View file

@ -15,8 +15,12 @@ formats:
# Optionally set the version of Python and requirements required to build your docs # Optionally set the version of Python and requirements required to build your docs
python: python:
version: 3
install: install:
- method: pip - method: pip
path: . path: .
- requirements: docs/requirements-docs.txt - requirements: docs/requirements-docs.txt
build:
os: ubuntu-20.04
tools:
python: "3" # latest stable cpython version

8
CHANGES.rst
View file

@ -72,9 +72,9 @@ New Features:
by `DonalDuck004 <https://github.com/DonalDuck004>`__) by `DonalDuck004 <https://github.com/DonalDuck004>`__)
- Add Method ``drop_chat/user_data`` to ``Dispatcher`` and Persistence - Add Method ``drop_chat/user_data`` to ``Dispatcher`` and Persistence
(`#2852 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2852>`__) (`#2852 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2852>`__)
- Add methods ``ChatPermissions.{all, no}_permissions`` ([#2948] - Add methods ``ChatPermissions.{all, no}_permissions`` (`#2948 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2948>`__)
- Full Support for API 6.0 - Full Support for API 6.0
(`#2956 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2956>`__)(https://github.com/python-telegram-bot/python-telegram-bot/pull/2948)) (`#2956 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2956>`__)
- Add Python 3.10 to Test Suite - Add Python 3.10 to Test Suite
(`#2968 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2968>`__) (`#2968 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2968>`__)
@ -1520,7 +1520,7 @@ Changes
- Lots of small improvements to our tests and documentation. - Lots of small improvements to our tests and documentation.
.. _`see docs`: http://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.dispatcher.html#telegram.ext.Dispatcher.add_handler .. _`see docs`: https://docs.python-telegram-bot.org/en/stable/telegram.ext.dispatcher.html#telegram.ext.Dispatcher.add_handler
.. _`#777`: https://github.com/python-telegram-bot/python-telegram-bot/pull/777 .. _`#777`: https://github.com/python-telegram-bot/python-telegram-bot/pull/777
.. _`#806`: https://github.com/python-telegram-bot/python-telegram-bot/pull/806 .. _`#806`: https://github.com/python-telegram-bot/python-telegram-bot/pull/806
.. _`#766`: https://github.com/python-telegram-bot/python-telegram-bot/pull/766 .. _`#766`: https://github.com/python-telegram-bot/python-telegram-bot/pull/766
@ -1762,7 +1762,7 @@ Pre-version 7.0
- Implement Bot API 2.0 - Implement Bot API 2.0
- Almost complete recode of ``Dispatcher`` - Almost complete recode of ``Dispatcher``
- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_ - Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-4.0>`_
**2016-03-22** **2016-03-22**

2
CODE_OF_CONDUCT.rst
View file

@ -49,4 +49,4 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
Attribution Attribution
=========== ===========
This Code of Conduct is adapted from the `Contributor Covenant <http://contributor-covenant.org>`_, version 1.4, available at `http://contributor-covenant.org/version/1/4 <http://contributor-covenant.org/version/1/4/>`_. This Code of Conduct is adapted from the `Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4, available at `https://www.contributor-covenant.org/version/1/4 <https://www.contributor-covenant.org/version/1/4/>`_.

18
README.rst
View file

@ -1,7 +1,7 @@
.. ..
Make sure to apply any changes to this file to README_RAW.rst as well! Make sure to apply any changes to this file to README_RAW.rst as well!
.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true .. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png
:align: center :align: center
:target: https://python-telegram-bot.org :target: https://python-telegram-bot.org
:alt: python-telegram-bot Logo :alt: python-telegram-bot Logo
@ -23,7 +23,7 @@
:alt: PyPi Package Monthly Download :alt: PyPi Package Monthly Download
.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable .. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
:target: https://python-telegram-bot.readthedocs.io/en/stable/ :target: https://docs.python-telegram-bot.org/en/stable/
:alt: Documentation Status :alt: Documentation Status
.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg .. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
@ -34,16 +34,16 @@
:target: https://github.com/python-telegram-bot/python-telegram-bot/ :target: https://github.com/python-telegram-bot/python-telegram-bot/
:alt: Github Actions workflow :alt: Github Actions workflow
.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg .. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
:target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
:alt: Code coverage :alt: Code coverage
.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg .. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
:target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
:alt: Median time to resolve an issue :alt: Median time to resolve an issue
.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968 .. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
:target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=python-telegram-bot/python-telegram-bot&amp;utm_campaign=Badge_Grade :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
:alt: Code quality: Codacy :alt: Code quality: Codacy
.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues .. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
@ -136,7 +136,7 @@ Optional Dependencies
PTB can be installed with optional dependencies: PTB can be installed with optional dependencies:
* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality. * ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
* ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server. * ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
Quick Start Quick Start
@ -148,7 +148,7 @@ Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/
Resources Resources
========= =========
- The `package documentation <https://python-telegram-bot.readthedocs.io/>`_ is the technical reference for ``python-telegram-bot``. - The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
It contains descriptions of all available classes, modules, methods and arguments. It contains descriptions of all available classes, modules, methods and arguments.
- The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation. - The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
- Our `examples directory <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. - Our `examples directory <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.

16
README_RAW.rst
View file

@ -23,7 +23,7 @@
:alt: PyPi Package Monthly Download :alt: PyPi Package Monthly Download
.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable .. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
:target: https://python-telegram-bot.readthedocs.io/ :target: https://docs.python-telegram-bot.org/
:alt: Documentation Status :alt: Documentation Status
.. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg .. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg
@ -34,16 +34,16 @@
:target: https://github.com/python-telegram-bot/python-telegram-bot/ :target: https://github.com/python-telegram-bot/python-telegram-bot/
:alt: Github Actions workflow :alt: Github Actions workflow
.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg .. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
:target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
:alt: Code coverage :alt: Code coverage
.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg .. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
:target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
:alt: Median time to resolve an issue :alt: Median time to resolve an issue
.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968 .. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
:target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=python-telegram-bot/python-telegram-bot&amp;utm_campaign=Badge_Grade :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
:alt: Code quality: Codacy :alt: Code quality: Codacy
.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues .. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
@ -134,7 +134,7 @@ Optional Dependencies
``python-telegram-bot-raw`` can be installed with optional dependencies: ``python-telegram-bot-raw`` can be installed with optional dependencies:
* ``pip install python-telegram-bot[passport]`` installs the `cryptography <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality. * ``pip install python-telegram-bot[passport]`` installs the `cryptography <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
* ``pip install python-telegram-bot[socks]`` installs the `PySocks <https://pypi.org/project/PySocks/>`_ library. Use this, if you want to work behind a Socks5 server. * ``pip install python-telegram-bot[socks]`` installs the `PySocks <https://pypi.org/project/PySocks/>`_ library. Use this, if you want to work behind a Socks5 server.
Quick Start Quick Start
@ -145,7 +145,7 @@ Our Wiki contains an `Introduction to the API <https://github.com/python-telegra
Resources Resources
========= =========
- The `package documentation <https://python-telegram-bot.readthedocs.io/>`_ is the technical reference for ``python-telegram-bot``. - The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
It contains descriptions of all available classes, modules, methods and arguments. It contains descriptions of all available classes, modules, methods and arguments.
- The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation. - The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
- Our `examples directory <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. - Our `examples directory <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.

9
docs/requirements-docs.txt
View file

@ -1,7 +1,4 @@
sphinx==4.5.0 sphinx==5.0.1
sphinx-pypi-upload sphinx-pypi-upload
furo==2022.04.07 furo==2022.6.4
# Can be replaced with a sphinx-paramlinks==... dependency once a version is released that sphinx-paramlinks==0.5.4
# includes the commit mentioned below and maybe even
# https://github.com/sqlalchemyorg/sphinx-paramlinks/pull/14
git+https://github.com/sqlalchemyorg/sphinx-paramlinks.git@acedb03149e3f87ff599174b033754c2f58f1c95

232
docs/source/conf.py
View file

@ -1,16 +1,3 @@
# -*- coding: utf-8 -*-
#
# Python Telegram Bot documentation build configuration file, created by
# sphinx-quickstart on Mon Aug 10 22:25:07 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import inspect import inspect
import os import os
import re import re
@ -32,6 +19,19 @@ from sphinx.util import logging
sys.path.insert(0, os.path.abspath("../..")) sys.path.insert(0, os.path.abspath("../.."))
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------
# General information about the project.
project = "python-telegram-bot"
copyright = "2015-2022, Leandro Toledo"
author = "Leandro Toledo"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = "20.0a0" # telegram.__version__[:3]
# The full version, including alpha/beta/rc tags.
release = "20.0a0" # 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 = "4.5.0"
@ -53,76 +53,49 @@ intersphinx_mapping = {
"APScheduler": ("https://apscheduler.readthedocs.io/en/3.x/", None), "APScheduler": ("https://apscheduler.readthedocs.io/en/3.x/", None),
} }
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = ".rst"
# The master toctree document.
master_doc = "index"
# -- Extension settings ------------------------------------------------
napoleon_use_admonition_for_examples = True
# Don't show type hints in the signature - that just makes it hardly readable # Don't show type hints in the signature - that just makes it hardly readable
# and we document the types anyway # and we document the types anyway
autodoc_typehints = "none" autodoc_typehints = "none"
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# Fail on warnings & unresolved references etc # Fail on warnings & unresolved references etc
nitpicky = True nitpicky = True
# Paramlink style # Paramlink style
paramlinks_hyperlink_param = "name" paramlinks_hyperlink_param = "name"
# Linkcheck settings
linkcheck_ignore = [
# Let's not check issue/PR links - that's wasted resources
r"http(s)://github\.com/python-telegram-bot/python-telegram-bot/(issues|pull)/\d+/?",
# For some reason linkcheck has a problem with these two:
re.escape("https://github.com/python-telegram-bot/python-telegram-bot/discussions/new"),
re.escape("https://github.com/python-telegram-bot/python-telegram-bot/issues/new"),
# Anchors are apparently inserted by GitHub dynamically, so let's skip checking them
"https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples#",
r"https://github\.com/python-telegram-bot/python-telegram-bot/wiki/[\w\-_,]+\#",
]
linkcheck_allowed_redirects = {
# Redirects to the default version are okay
r"https://docs\.python-telegram-bot\.org/.*": r"https://docs\.python-telegram-bot\.org/en/[\w\d\.]+/.*",
# pre-commit.ci always redirects to the latest run
re.escape(
"https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master"
): r"https://results\.pre-commit\.ci/run/github/.*",
}
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = ".rst"
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = "index"
# General information about the project.
project = "python-telegram-bot"
copyright = "2015-2021, Leandro Toledo"
author = "Leandro Toledo"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = "20.0a0" # telegram.__version__[:3]
# The full version, including alpha/beta/rc tags.
release = "20.0a0" # telegram.__version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use. # The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx" pygments_style = "sphinx"
@ -130,16 +103,9 @@ pygments_style = "sphinx"
# Decides the language used for syntax highlighting of code blocks. # Decides the language used for syntax highlighting of code blocks.
highlight_language = "python3" highlight_language = "python3"
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing. # If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False todo_include_todos = False
# -- Options for HTML output ---------------------------------------------- # -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for # The theme to use for HTML and HTML Help pages. See the documentation for
@ -228,16 +194,10 @@ html_theme_options = {
], ],
} }
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to # The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation". # "<project> v<release> documentation".
html_title = f"python-telegram-bot<br> v{version}" html_title = f"python-telegram-bot<br> v{version}"
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top # The name of an image file (relative to this directory) to place at the top
# of the sidebar. # of the sidebar.
html_logo = "ptb-logo_1024.png" html_logo = "ptb-logo_1024.png"
@ -251,72 +211,16 @@ 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 = ["style_external_link.css"] html_css_files = ["style_external_link.css"]
html_permalinks_icon = "" # Furo's default permalink icon is `#`` which doesn't look great imo.
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
# html_search_scorer = 'scorer.js'
# 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"
# The base URL which points to the root of the HTML documentation. It is used to indicate the
# location of document using The Canonical Link Relation. Default: ''.
html_baseurl = "https://docs.python-telegram-bot.org"
# -- Options for LaTeX output --------------------------------------------- # -- Options for LaTeX output ---------------------------------------------
latex_elements = { latex_elements = {
@ -343,32 +247,12 @@ latex_documents = [
# the title page. # the title page.
latex_logo = "ptb-logo_1024.png" latex_logo = "ptb-logo_1024.png"
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output --------------------------------------- # -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples # One entry per manual page. List of tuples
# (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)]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output ------------------------------------------- # -- Options for Texinfo output -------------------------------------------
@ -387,22 +271,6 @@ texinfo_documents = [
), ),
] ]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# Napoleon stuff
napoleon_use_admonition_for_examples = True
# -- script stuff -------------------------------------------------------- # -- script stuff --------------------------------------------------------
# get the sphinx(!) logger # get the sphinx(!) logger

14
docs/source/telegram.ext.rst
View file

@ -3,16 +3,16 @@ telegram.ext package
.. toctree:: .. toctree::
telegram.ext.extbot
telegram.ext.applicationbuilder
telegram.ext.application telegram.ext.application
telegram.ext.applicationbuilder
telegram.ext.applicationhandlerstop telegram.ext.applicationhandlerstop
telegram.ext.updater
telegram.ext.callbackcontext telegram.ext.callbackcontext
telegram.ext.job
telegram.ext.jobqueue
telegram.ext.contexttypes telegram.ext.contexttypes
telegram.ext.defaults telegram.ext.defaults
telegram.ext.extbot
telegram.ext.job
telegram.ext.jobqueue
telegram.ext.updater
Handlers Handlers
-------- --------
@ -26,9 +26,9 @@ Handlers
telegram.ext.choseninlineresulthandler telegram.ext.choseninlineresulthandler
telegram.ext.commandhandler telegram.ext.commandhandler
telegram.ext.conversationhandler telegram.ext.conversationhandler
telegram.ext.filters
telegram.ext.inlinequeryhandler telegram.ext.inlinequeryhandler
telegram.ext.messagehandler telegram.ext.messagehandler
telegram.ext.filters
telegram.ext.pollanswerhandler telegram.ext.pollanswerhandler
telegram.ext.pollhandler telegram.ext.pollhandler
telegram.ext.precheckoutqueryhandler telegram.ext.precheckoutqueryhandler
@ -44,9 +44,9 @@ Persistence
.. toctree:: .. toctree::
telegram.ext.basepersistence telegram.ext.basepersistence
telegram.ext.dictpersistence
telegram.ext.persistenceinput telegram.ext.persistenceinput
telegram.ext.picklepersistence telegram.ext.picklepersistence
telegram.ext.dictpersistence
Arbitrary Callback Data Arbitrary Callback Data
----------------------- -----------------------

58
docs/source/telegram.rst
View file

@ -17,13 +17,13 @@ Available Types
telegram.bot telegram.bot
telegram.botcommand telegram.botcommand
telegram.botcommandscope telegram.botcommandscope
telegram.botcommandscopedefault
telegram.botcommandscopeallprivatechats
telegram.botcommandscopeallgroupchats
telegram.botcommandscopeallchatadministrators telegram.botcommandscopeallchatadministrators
telegram.botcommandscopeallgroupchats
telegram.botcommandscopeallprivatechats
telegram.botcommandscopechat telegram.botcommandscopechat
telegram.botcommandscopechatadministrators telegram.botcommandscopechatadministrators
telegram.botcommandscopechatmember telegram.botcommandscopechatmember
telegram.botcommandscopedefault
telegram.callbackquery telegram.callbackquery
telegram.chat telegram.chat
telegram.chatadministratorrights telegram.chatadministratorrights
@ -31,12 +31,12 @@ Available Types
telegram.chatjoinrequest telegram.chatjoinrequest
telegram.chatlocation telegram.chatlocation
telegram.chatmember telegram.chatmember
telegram.chatmemberowner
telegram.chatmemberadministrator telegram.chatmemberadministrator
telegram.chatmembermember
telegram.chatmemberrestricted
telegram.chatmemberleft
telegram.chatmemberbanned telegram.chatmemberbanned
telegram.chatmemberleft
telegram.chatmembermember
telegram.chatmemberowner
telegram.chatmemberrestricted
telegram.chatmemberupdated telegram.chatmemberupdated
telegram.chatpermissions telegram.chatpermissions
telegram.chatphoto telegram.chatphoto
@ -64,15 +64,15 @@ Available Types
telegram.menubuttonwebapp telegram.menubuttonwebapp
telegram.message telegram.message
telegram.messageautodeletetimerchanged telegram.messageautodeletetimerchanged
telegram.messageid
telegram.messageentity telegram.messageentity
telegram.messageid
telegram.photosize telegram.photosize
telegram.poll telegram.poll
telegram.pollanswer telegram.pollanswer
telegram.polloption telegram.polloption
telegram.proximityalerttriggered telegram.proximityalerttriggered
telegram.replykeyboardremove
telegram.replykeyboardmarkup telegram.replykeyboardmarkup
telegram.replykeyboardremove
telegram.sentwebappmessage telegram.sentwebappmessage
telegram.telegramobject telegram.telegramobject
telegram.update telegram.update
@ -95,15 +95,16 @@ Stickers
.. toctree:: .. toctree::
telegram.maskposition
telegram.sticker telegram.sticker
telegram.stickerset telegram.stickerset
telegram.maskposition
Inline Mode Inline Mode
----------- -----------
.. toctree:: .. toctree::
telegram.choseninlineresult
telegram.inlinequery telegram.inlinequery
telegram.inlinequeryresult telegram.inlinequeryresult
telegram.inlinequeryresultarticle telegram.inlinequeryresultarticle
@ -132,29 +133,28 @@ Inline Mode
telegram.inputvenuemessagecontent telegram.inputvenuemessagecontent
telegram.inputcontactmessagecontent telegram.inputcontactmessagecontent
telegram.inputinvoicemessagecontent telegram.inputinvoicemessagecontent
telegram.choseninlineresult
Payments Payments
-------- --------
.. toctree:: .. toctree::
telegram.labeledprice
telegram.invoice telegram.invoice
telegram.shippingaddress telegram.labeledprice
telegram.orderinfo telegram.orderinfo
telegram.shippingoption
telegram.successfulpayment
telegram.shippingquery
telegram.precheckoutquery telegram.precheckoutquery
telegram.shippingaddress
telegram.shippingoption
telegram.shippingquery
telegram.successfulpayment
Games Games
----- -----
.. toctree:: .. toctree::
telegram.game
telegram.callbackgame telegram.callbackgame
telegram.game
telegram.gamehighscore telegram.gamehighscore
Passport Passport
@ -162,25 +162,25 @@ Passport
.. toctree:: .. toctree::
telegram.credentials
telegram.datacredentials
telegram.encryptedcredentials
telegram.encryptedpassportelement
telegram.filecredentials
telegram.iddocumentdata
telegram.passportdata
telegram.passportelementerror telegram.passportelementerror
telegram.passportelementerrordatafield
telegram.passportelementerrorfile telegram.passportelementerrorfile
telegram.passportelementerrorfiles telegram.passportelementerrorfiles
telegram.passportelementerrorreverseside
telegram.passportelementerrorfrontside telegram.passportelementerrorfrontside
telegram.passportelementerrordatafield telegram.passportelementerrorreverseside
telegram.passportelementerrorselfie telegram.passportelementerrorselfie
telegram.passportelementerrortranslationfile telegram.passportelementerrortranslationfile
telegram.passportelementerrortranslationfiles telegram.passportelementerrortranslationfiles
telegram.passportelementerrorunspecified telegram.passportelementerrorunspecified
telegram.credentials telegram.passportfile
telegram.datacredentials
telegram.securedata
telegram.securevalue
telegram.filecredentials
telegram.iddocumentdata
telegram.personaldetails telegram.personaldetails
telegram.residentialaddress telegram.residentialaddress
telegram.passportdata telegram.securedata
telegram.passportfile telegram.securevalue
telegram.encryptedpassportelement
telegram.encryptedcredentials

58
examples/README.md
View file

@ -1,71 +1,71 @@
# Examples # Examples
## ⚠️ The examples in this directory are subject to changes and may not work on the PTB version that you are using. You can find the examples compatible with a specific version at https://github.com/python-telegram-bot/python-telegram-bot/tree/v<X.Y>/examples ## ⚠️ The examples in this directory are subject to changes and may not work on the PTB version that you are using. You can find the examples compatible with a specific version at https://github.com/python-telegram-bot/python-telegram-bot/tree/v<X.Y>/examples
In this folder are small examples to show what a bot written with `python-telegram-bot` looks like. Some bots focus on one specific aspect of the Telegram Bot API while others focus on one of the mechanics of this library. Except for the [`rawapibot.py`](#pure-api) example, they all use the high-level framework this library provides with the [`telegram.ext`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.html) submodule. In this folder are small examples to show what a bot written with `python-telegram-bot` looks like. Some bots focus on one specific aspect of the Telegram Bot API while others focus on one of the mechanics of this library. Except for the [`rawapibot.py`](#pure-api) example, they all use the high-level framework this library provides with the [`telegram.ext`](https://docs.python-telegram-bot.org/telegram.ext.html) submodule.
All examples are licensed under the [CC0 License](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights. All examples are licensed under the [CC0 License](LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights.
Do note that we ignore one pythonic convention. Best practice would dictate, in many handler callbacks function signatures, to replace the argument `context` with an underscore, since `context` is an unused local variable in those callbacks. However, since these are examples and not having a name for that argument confuses beginners, we decided to have it present. Do note that we ignore one pythonic convention. Best practice would dictate, in many handler callbacks function signatures, to replace the argument `context` with an underscore, since `context` is an unused local variable in those callbacks. However, since these are examples and not having a name for that argument confuses beginners, we decided to have it present.
### [`echobot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py) ### [`echobot.py`](echobot.py)
This is probably the base for most of the bots made with `python-telegram-bot`. It simply replies to each text message with a message that contains the same text. This is probably the base for most of the bots made with `python-telegram-bot`. It simply replies to each text message with a message that contains the same text.
### [`timerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py) ### [`timerbot.py`](timerbot.py)
This bot uses the [`JobQueue`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.jobqueue.html) class to send timed messages. The user sets a timer by using `/set` command with a specific time, for example `/set 30`. The bot then sets up a job to send a message to that user after 30 seconds. The user can also cancel the timer by sending `/unset`. To learn more about the `JobQueue`, read [this wiki article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue). This bot uses the [`JobQueue`](https://docs.python-telegram-bot.org/telegram.ext.jobqueue.html) class to send timed messages. The user sets a timer by using `/set` command with a specific time, for example `/set 30`. The bot then sets up a job to send a message to that user after 30 seconds. The user can also cancel the timer by sending `/unset`. To learn more about the `JobQueue`, read [this wiki article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue).
### [`conversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.py) ### [`conversationbot.py`](conversationbot.py)
A common task for a bot is to ask information from the user. In v5.0 of this library, we introduced the [`ConversationHandler`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.conversationhandler.html) for that exact purpose. This example uses it to retrieve user-information in a conversation-like style. To get a better understanding, take a look at the [state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.png). A common task for a bot is to ask information from the user. In v5.0 of this library, we introduced the [`ConversationHandler`](https://docs.python-telegram-bot.org/telegram.ext.conversationhandler.html) for that exact purpose. This example uses it to retrieve user-information in a conversation-like style. To get a better understanding, take a look at the [state diagram](conversationbot.png).
### [`conversationbot2.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot2.py) ### [`conversationbot2.py`](conversationbot2.py)
A more complex example of a bot that uses the `ConversationHandler`. It is also more confusing. Good thing there is a [fancy state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot2.png) for this one, too! A more complex example of a bot that uses the `ConversationHandler`. It is also more confusing. Good thing there is a [fancy state diagram](conversationbot2.png) for this one, too!
### [`nestedconversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/nestedconversationbot.py) ### [`nestedconversationbot.py`](nestedconversationbot.py)
A even more complex example of a bot that uses the nested `ConversationHandler`s. While it's certainly not that complex that you couldn't built it without nested `ConversationHanldler`s, it gives a good impression on how to work with them. Of course, there is a [fancy state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/nestedconversationbot.png) for this example, too! A even more complex example of a bot that uses the nested `ConversationHandler`s. While it's certainly not that complex that you couldn't built it without nested `ConversationHanldler`s, it gives a good impression on how to work with them. Of course, there is a [fancy state diagram](nestedconversationbot.png) for this example, too!
### [`persistentconversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/persistentconversationbot.py) ### [`persistentconversationbot.py`](persistentconversationbot.py)
A basic example of a bot store conversation state and user_data over multiple restarts. A basic example of a bot store conversation state and user_data over multiple restarts.
### [`inlinekeyboard.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinekeyboard.py) ### [`inlinekeyboard.py`](inlinekeyboard.py)
This example sheds some light on inline keyboards, callback queries and message editing. A wiki site explaining this examples lives [here](https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example). This example sheds some light on inline keyboards, callback queries and message editing. A wiki site explaining this examples lives [here](https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example).
### [`inlinekeyboard2.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinekeyboard2.py) ### [`inlinekeyboard2.py`](inlinekeyboard2.py)
A more complex example about inline keyboards, callback queries and message editing. This example showcases how an interactive menu could be build using inline keyboards. A more complex example about inline keyboards, callback queries and message editing. This example showcases how an interactive menu could be build using inline keyboards.
### [`deeplinking.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/deeplinking.py) ### [`deeplinking.py`](deeplinking.py)
A basic example on how to use deeplinking with inline keyboards. A basic example on how to use deeplinking with inline keyboards.
### [`inlinebot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinebot.py) ### [`inlinebot.py`](inlinebot.py)
A basic example of an [inline bot](https://core.telegram.org/bots/inline). Don't forget to enable inline mode with [@BotFather](https://telegram.me/BotFather). A basic example of an [inline bot](https://core.telegram.org/bots/inline). Don't forget to enable inline mode with [@BotFather](https://t.me/BotFather).
### [`pollbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/pollbot.py) ### [`pollbot.py`](pollbot.py)
This example sheds some light on polls, poll answers and the corresponding handlers. This example sheds some light on polls, poll answers and the corresponding handlers.
### [`passportbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/passportbot.py) ### [`passportbot.py`](passportbot.py)
A basic example of a bot that can accept passports. Use in combination with [`passportbot.html`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/passportbot.html). Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather). Check out this [guide](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport) on Telegram passports in PTB. A basic example of a bot that can accept passports. Use in combination with [`passportbot.html`](passportbot.html). Don't forget to enable and configure payments with [@BotFather](https://t.me/BotFather). Check out this [guide](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport) on Telegram passports in PTB.
### [`paymentbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/paymentbot.py) ### [`paymentbot.py`](paymentbot.py)
A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather). A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://t.me/BotFather).
### [`errorhandlerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/errorhandlerbot.py) ### [`errorhandlerbot.py`](errorhandlerbot.py)
A basic example on how to set up a custom error handler. A basic example on how to set up a custom error handler.
### [`chatmemberbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/chatmemberbot.py) ### [`chatmemberbot.py`](chatmemberbot.py)
A basic example on how `(my_)chat_member` updates can be used. A basic example on how `(my_)chat_member` updates can be used.
### [`webappbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/webappbot.py) ### [`webappbot.py`](webappbot.py)
A basic example of how [Telegram WebApps](https://core.telegram.org/bots/webapps) can be used. A basic example of how [Telegram WebApps](https://core.telegram.org/bots/webapps) can be used.
Use in combination with [`webappbot.html`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/webappbot.html). Use in combination with [`webappbot.html`](webappbot.html).
For your convenience, this file is hosted by the PTB team such that you don't need to host it yourself. For your convenience, this file is hosted by the PTB team such that you don't need to host it yourself.
Uses the [`iro.js`](https://iro.js.org) JavaScript library to showcase a user interface that is hard to achieve with native Telegram functionality. Uses the [`iro.js`](https://iro.js.org) JavaScript library to showcase a user interface that is hard to achieve with native Telegram functionality.
### [`contexttypesbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/contexttypesbot.py) ### [`contexttypesbot.py`](contexttypesbot.py)
This example showcases how `telegram.ext.ContextTypes` can be used to customize the `context` argument of handler and job callbacks. This example showcases how `telegram.ext.ContextTypes` can be used to customize the `context` argument of handler and job callbacks.
### [`customwebhookbot.py`](customwebhookbot.py) ### [`customwebhookbot.py`](customwebhookbot.py)
This example showcases how a custom webhook setup can be used in combination with `telegram.ext.Application`. This example showcases how a custom webhook setup can be used in combination with `telegram.ext.Application`.
### [`arbitrarycallbackdatabot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/arbitrarycallbackdatabot.py) ### [`arbitrarycallbackdatabot.py`](arbitrarycallbackdatabot.py)
This example showcases how PTBs "arbitrary callback data" feature can be used. This example showcases how PTBs "arbitrary callback data" feature can be used.
## Pure API ## Pure API
The [`rawapibot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/rawapibot.py) example uses only the pure, "bare-metal" API wrapper. The [`rawapibot.py`](rawapibot.py) example uses only the pure, "bare-metal" API wrapper.

2
examples/inlinebot.py
View file

@ -3,6 +3,8 @@
# This program is dedicated to the public domain under the CC0 license. # This program is dedicated to the public domain under the CC0 license.
""" """
Don't forget to enable inline mode with @BotFather
First, a few handler functions are defined. Then, those functions are passed to First, a few handler functions are defined. Then, those functions are passed to
the Application and registered at their respective places. the Application and registered at their respective places.
Then, the bot is started and runs until we press Ctrl-C on the command line. Then, the bot is started and runs until we press Ctrl-C on the command line.

4
setup.py
View file

@ -56,11 +56,11 @@ def get_setup_kwargs(raw=False):
url="https://python-telegram-bot.org/", url="https://python-telegram-bot.org/",
# Keywords supported by PyPI can be found at https://github.com/pypa/warehouse/blob/aafc5185e57e67d43487ce4faa95913dd4573e14/warehouse/templates/packaging/detail.html#L20-L58 # Keywords supported by PyPI can be found at https://github.com/pypa/warehouse/blob/aafc5185e57e67d43487ce4faa95913dd4573e14/warehouse/templates/packaging/detail.html#L20-L58
project_urls={ project_urls={
"Documentation": "https://python-telegram-bot.readthedocs.io", "Documentation": "https://docs.python-telegram-bot.org",
"Bug Tracker": "https://github.com/python-telegram-bot/python-telegram-bot/issues", "Bug Tracker": "https://github.com/python-telegram-bot/python-telegram-bot/issues",
"Source Code": "https://github.com/python-telegram-bot/python-telegram-bot", "Source Code": "https://github.com/python-telegram-bot/python-telegram-bot",
"News": "https://t.me/pythontelegrambotchannel", "News": "https://t.me/pythontelegrambotchannel",
"Changelog": "https://python-telegram-bot.readthedocs.io/en/stable/changelog.html", "Changelog": "https://docs.python-telegram-bot.org/en/stable/changelog.html",
}, },
download_url=f"https://pypi.org/project/python-telegram-bot{raw_ext}/", download_url=f"https://pypi.org/project/python-telegram-bot{raw_ext}/",
keywords="python telegram bot api wrapper", keywords="python telegram bot api wrapper",

44
telegram/_bot.py
View file

@ -1230,7 +1230,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers. Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers.
Note: Note:
The sticker argument can be either a file_id, an URL or a file from disk The :paramref:`sticker` argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')`` ``open(filename, 'rb')``
Args: Args:
@ -1334,11 +1334,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
changed in the future. changed in the future.
Note: Note:
* The video argument can be either a file_id, an URL or a file from disk * The :paramref:`video` argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')`` ``open(filename, 'rb')``
* ``thumb`` will be ignored for small video files, for which Telegram can easily * :paramref:`thumb` will be ignored for small video files, for which Telegram can
generate thumb nails. However, this behaviour is undocumented and might be changed easily generate thumbnails. However, this behaviour is undocumented and might be
by Telegram. changed by Telegram.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -1480,11 +1480,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Use this method to send video messages. Use this method to send video messages.
Note: Note:
* The video_note argument can be either a file_id or a file from disk * The :paramref:`video_note` argument can be either a file_id or a file from disk
``open(filename, 'rb')`` ``open(filename, 'rb')``
* ``thumb`` will be ignored for small video files, for which Telegram can easily * :paramref:`thumb` will be ignored for small video files, for which Telegram can
generate thumb nails. However, this behaviour is undocumented and might be changed easily generate thumbnails. However, this behaviour is undocumented and might be
by Telegram. changed by Telegram.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -1757,11 +1757,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
in size, this limit may be changed in the future. in size, this limit may be changed in the future.
Note: Note:
* The voice argument can be either a file_id, an URL or a file from disk * The :paramref:`voice` argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')``. ``open(filename, 'rb')``.
* To use this method, the file must have the type ``audio/ogg`` and be no more than 1MB * To use this method, the file must have the type :mimetype:`audio/ogg` and be no more
in size. 1-20MB voice notes will be sent as files. than ``1MB`` in size. ``1-20MB`` voice notes will be sent as files.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -2272,10 +2272,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
Note: Note:
* You can either supply :paramref:`venue`, or :paramref:`latitude`, * You can either supply :paramref:`venue`, or :paramref:`latitude`,
:paramref:`longitude`, :paramref:`longitude`, :paramref:`title` and :paramref:`address` and optionally
:paramref:title` and :paramref:address` and optionally :paramref:`foursquare_id` and :paramref:`foursquare_id` and :paramref:`foursquare_type` or optionally
:paramref:`foursquare_type` or optionally :paramref:`google_place_id` and :paramref:`google_place_id` and :paramref:`google_place_type`.
:paramref:`google_place_type`.
* Foursquare details and Google Place details are mutually exclusive. However, this * Foursquare details and Google Place details are mutually exclusive. However, this
behaviour is undocumented and might be changed by Telegram. behaviour is undocumented and might be changed by Telegram.
@ -2293,7 +2292,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
google_place_id (:obj:`str`, optional): Google Places identifier of the venue. google_place_id (:obj:`str`, optional): Google Places identifier of the venue.
google_place_type (:obj:`str`, optional): Google Places type of the venue. (See google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
`supported types \ `supported types \
<https://developers.google.com/places/web-service/supported_types>`_.) <https://developers.google.com/maps/documentation/places/web-service/supported_types>`_.)
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound. receive a notification with no sound.
protect_content (:obj:`bool`, optional): Protects the contents of the sent message from protect_content (:obj:`bool`, optional): Protects the contents of the sent message from
@ -3811,7 +3810,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
If you'd like to make sure that the Webhook request comes from Telegram, Telegram If you'd like to make sure that the Webhook request comes from Telegram, Telegram
recommends using a secret path in the URL, e.g. https://www.example.com/<token>. Since recommends using a secret path in the URL, e.g. https://www.example.com/<token>. Since
nobody else knows your bot's token, you can be pretty sure it's us. nobody else knows your bot's token, you can be pretty sure it's them.
Note: Note:
The certificate argument should be a file from disk ``open(filename, 'rb')``. The certificate argument should be a file from disk ``open(filename, 'rb')``.
@ -3821,7 +3820,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
integration. integration.
certificate (:term:`file object`): Upload your public key certificate so that the root certificate (:term:`file object`): Upload your public key certificate so that the root
certificate in use can be checked. See our self-signed guide for details. certificate in use can be checked. See our self-signed guide for details.
(https://goo.gl/rw7w6Y) (https://github.com/python-telegram-bot/python-telegram-bot/wiki/Webhooks#\
creating-a-self-signed-certificate-using-openssl)
ip_address (:obj:`str`, optional): The fixed IP address which will be used to send ip_address (:obj:`str`, optional): The fixed IP address which will be used to send
webhook requests instead of the IP address resolved through DNS. webhook requests instead of the IP address resolved through DNS.
max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS
@ -4140,7 +4140,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
) -> int: ) -> int:
"""Use this method to get the number of members in a chat. """Use this method to get the number of members in a chat.
.. versionadded:: 13.7 .. versionadded:: 13.7
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -6202,8 +6202,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
times). times).
Note: Note:
The png_sticker argument can be either a file_id, an URL or a file from disk The :paramref:`png_sticker` argument can be either a file_id, an URL or a file from
``open(filename, 'rb')`` disk ``open(filename, 'rb')``
Args: Args:
user_id (:obj:`int`): User identifier of sticker file owner. user_id (:obj:`int`): User identifier of sticker file owner.

93
telegram/_callbackquery.py
View file

@ -65,7 +65,6 @@ class CallbackQuery(TelegramObject):
.. versionadded:: 13.6 .. versionadded:: 13.6
Args: Args:
id (:obj:`str`): Unique identifier for this query. id (:obj:`str`): Unique identifier for this query.
from_user (:class:`telegram.User`): Sender. from_user (:class:`telegram.User`): Sender.
@ -74,8 +73,8 @@ class CallbackQuery(TelegramObject):
message (:class:`telegram.Message`, optional): Message with the callback button that message (:class:`telegram.Message`, optional): Message with the callback button that
originated the query. Note that message content and message date will not be available originated the query. Note that message content and message date will not be available
if the message is too old. if the message is too old.
data (:obj:`str`, optional): Data associated with the callback button. Be aware that a bad data (:obj:`str`, optional): Data associated with the callback button. Be aware that the
client can send arbitrary data in this field. message, which originated the query, can contain no callback buttons with this data.
inline_message_id (:obj:`str`, optional): Identifier of the message sent via the bot in inline_message_id (:obj:`str`, optional): Identifier of the message sent via the bot in
inline mode, that originated the query. inline mode, that originated the query.
game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as
@ -90,6 +89,10 @@ class CallbackQuery(TelegramObject):
message (:class:`telegram.Message`): Optional. Message with the callback button that message (:class:`telegram.Message`): Optional. Message with the callback button that
originated the query. originated the query.
data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button. data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button.
Tip:
The value here is the same as the value passed in
:paramref:`telegram.InlineKeyboardButton.callback_data`.
inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in
inline mode, that originated the query. inline mode, that originated the query.
game_short_name (:obj:`str`): Optional. Short name of a Game to be returned. game_short_name (:obj:`str`): Optional. Short name of a Game to be returned.
@ -199,12 +202,13 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.edit_text(text, *args, **kwargs) await update.callback_query.message.edit_text(*args, **kwargs)
or:: or::
bot.edit_message_text(text, inline_message_id=update.callback_query.inline_message_id, await bot.edit_message_text(
*args, **kwargs) inline_message_id=update.callback_query.inline_message_id, *args, **kwargs,
)
For the documentation of the arguments, please see For the documentation of the arguments, please see
:meth:`telegram.Bot.edit_message_text` and :meth:`telegram.Message.edit_text`. :meth:`telegram.Bot.edit_message_text` and :meth:`telegram.Message.edit_text`.
@ -258,13 +262,13 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.edit_caption(caption, *args, **kwargs) await update.callback_query.message.edit_caption(*args, **kwargs)
or:: or::
bot.edit_message_caption(caption=caption await bot.edit_message_caption(
inline_message_id=update.callback_query.inline_message_id, inline_message_id=update.callback_query.inline_message_id, *args, **kwargs,
*args, **kwargs) )
For the documentation of the arguments, please see For the documentation of the arguments, please see
:meth:`telegram.Bot.edit_message_caption` and :meth:`telegram.Message.edit_caption`. :meth:`telegram.Bot.edit_message_caption` and :meth:`telegram.Message.edit_caption`.
@ -313,19 +317,12 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.edit_reply_markup( await update.callback_query.message.edit_reply_markup(*args, **kwargs)
reply_markup=reply_markup,
*args,
**kwargs
)
or:: or::
bot.edit_message_reply_markup await bot.edit_message_reply_markup(
inline_message_id=update.callback_query.inline_message_id, inline_message_id=update.callback_query.inline_message_id, *args, **kwargs
reply_markup=reply_markup,
*args,
**kwargs
) )
For the documentation of the arguments, please see For the documentation of the arguments, please see
@ -371,12 +368,13 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.edit_media(*args, **kwargs) await update.callback_query.message.edit_media(*args, **kwargs)
or:: or::
bot.edit_message_media(inline_message_id=update.callback_query.inline_message_id, await bot.edit_message_media(
*args, **kwargs) inline_message_id=update.callback_query.inline_message_id, *args, **kwargs
)
For the documentation of the arguments, please see For the documentation of the arguments, please see
:meth:`telegram.Bot.edit_message_media` and :meth:`telegram.Message.edit_media`. :meth:`telegram.Bot.edit_message_media` and :meth:`telegram.Message.edit_media`.
@ -427,13 +425,12 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.edit_live_location(*args, **kwargs) await update.callback_query.message.edit_live_location(*args, **kwargs)
or:: or::
bot.edit_message_live_location( await bot.edit_message_live_location(
inline_message_id=update.callback_query.inline_message_id, inline_message_id=update.callback_query.inline_message_id, *args, **kwargs
*args, **kwargs
) )
For the documentation of the arguments, please see For the documentation of the arguments, please see
@ -490,13 +487,12 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.stop_live_location(*args, **kwargs) await update.callback_query.message.stop_live_location(*args, **kwargs)
or:: or::
bot.stop_message_live_location( await bot.stop_message_live_location(
inline_message_id=update.callback_query.inline_message_id, inline_message_id=update.callback_query.inline_message_id, *args, **kwargs
*args, **kwargs
) )
For the documentation of the arguments, please see For the documentation of the arguments, please see
@ -544,12 +540,13 @@ class CallbackQuery(TelegramObject):
) -> Union[Message, bool]: ) -> Union[Message, bool]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.set_game_score(*args, **kwargs) await update.callback_query.message.set_game_score(*args, **kwargs)
or:: or::
bot.set_game_score(inline_message_id=update.callback_query.inline_message_id, await bot.set_game_score(
*args, **kwargs) inline_message_id=update.callback_query.inline_message_id, *args, **kwargs
)
For the documentation of the arguments, please see For the documentation of the arguments, please see
:meth:`telegram.Bot.set_game_score` and :meth:`telegram.Message.set_game_score`. :meth:`telegram.Bot.set_game_score` and :meth:`telegram.Message.set_game_score`.
@ -598,12 +595,13 @@ class CallbackQuery(TelegramObject):
) -> List["GameHighScore"]: ) -> List["GameHighScore"]:
"""Shortcut for either:: """Shortcut for either::
update.callback_query.message.get_game_high_score(*args, **kwargs) await update.callback_query.message.get_game_high_score(*args, **kwargs)
or:: or::
bot.get_game_high_scores(inline_message_id=update.callback_query.inline_message_id, await bot.get_game_high_scores(
*args, **kwargs) inline_message_id=update.callback_query.inline_message_id, *args, **kwargs
)
For the documentation of the arguments, please see For the documentation of the arguments, please see
:meth:`telegram.Bot.get_game_high_scores` and :meth:`telegram.Bot.get_game_high_scores` and
@ -645,10 +643,9 @@ class CallbackQuery(TelegramObject):
) -> bool: ) -> bool:
"""Shortcut for:: """Shortcut for::
update.callback_query.message.delete(*args, **kwargs) await update.callback_query.message.delete(*args, **kwargs)
For the documentation of the arguments, please see For the documentation of the arguments, please see :meth:`telegram.Message.delete`.
:meth:`telegram.Message.delete`.
Returns: Returns:
:obj:`bool`: On success, :obj:`True` is returned. :obj:`bool`: On success, :obj:`True` is returned.
@ -674,10 +671,9 @@ class CallbackQuery(TelegramObject):
) -> bool: ) -> bool:
"""Shortcut for:: """Shortcut for::
update.callback_query.message.pin(*args, **kwargs) await update.callback_query.message.pin(*args, **kwargs)
For the documentation of the arguments, please see For the documentation of the arguments, please see :meth:`telegram.Message.pin`.
:meth:`telegram.Message.pin`.
Returns: Returns:
:obj:`bool`: On success, :obj:`True` is returned. :obj:`bool`: On success, :obj:`True` is returned.
@ -703,10 +699,9 @@ class CallbackQuery(TelegramObject):
) -> bool: ) -> bool:
"""Shortcut for:: """Shortcut for::
update.callback_query.message.unpin(*args, **kwargs) await update.callback_query.message.unpin(*args, **kwargs)
For the documentation of the arguments, please see For the documentation of the arguments, please see :meth:`telegram.Message.unpin`.
:meth:`telegram.Message.unpin`.
Returns: Returns:
:obj:`bool`: On success, :obj:`True` is returned. :obj:`bool`: On success, :obj:`True` is returned.
@ -740,16 +735,14 @@ class CallbackQuery(TelegramObject):
) -> "MessageId": ) -> "MessageId":
"""Shortcut for:: """Shortcut for::
update.callback_query.message.copy( await update.callback_query.message.copy(
chat_id,
from_chat_id=update.message.chat_id, from_chat_id=update.message.chat_id,
message_id=update.message.message_id, message_id=update.message.message_id,
*args, *args,
**kwargs **kwargs
) )
For the documentation of the arguments, please see For the documentation of the arguments, please see :meth:`telegram.Message.copy`.
:meth:`telegram.Message.copy`.
Returns: Returns:
:class:`telegram.MessageId`: On success, returns the MessageId of the sent message. :class:`telegram.MessageId`: On success, returns the MessageId of the sent message.

6
telegram/_chat.py
View file

@ -81,10 +81,10 @@ class Chat(TelegramObject):
type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`, type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
:attr:`SUPERGROUP` or :attr:`CHANNEL`. :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, for private chats, supergroups and channels if username (:obj:`str`, optional): Username, for private chats, supergroups and channels if
available. 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`. 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

1
telegram/_chatmember.py
View file

@ -45,6 +45,7 @@ class ChatMember(TelegramObject):
considered equal, if their :attr:`user` and :attr:`status` are equal. considered equal, if their :attr:`user` and :attr:`status` are equal.
.. versionchanged:: 20.0 .. versionchanged:: 20.0
* As of Bot API 5.3, :class:`ChatMember` is nothing but the base class for the subclasses * As of Bot API 5.3, :class:`ChatMember` is nothing but the base class for the subclasses
listed above and is no longer returned directly by :meth:`~telegram.Bot.get_chat`. listed above and is no longer returned directly by :meth:`~telegram.Bot.get_chat`.
Therefore, most of the arguments and attributes were removed and you should no longer Therefore, most of the arguments and attributes were removed and you should no longer

2
telegram/_chatmemberupdated.py
View file

@ -166,7 +166,7 @@ class ChatMemberUpdated(TelegramObject):
Returns: Returns:
Dict[:obj:`str`, Tuple[:class:`object`, :class:`object`]]: A dictionary mapping Dict[:obj:`str`, Tuple[:class:`object`, :class:`object`]]: A dictionary mapping
attribute names to tuples of the form ``(old_value, new_value)`` attribute names to tuples of the form ``(old_value, new_value)``
""" """
# we first get the names of the attributes that have changed # we first get the names of the attributes that have changed
# user.to_dict() is unhashable, so that needs some special casing further down # user.to_dict() is unhashable, so that needs some special casing further down

3
telegram/_files/venue.py
View file

@ -47,7 +47,8 @@ class Venue(TelegramObject):
"arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".) "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".)
google_place_id (:obj:`str`, optional): Google Places identifier of the venue. google_place_id (:obj:`str`, optional): Google Places identifier of the venue.
google_place_type (:obj:`str`, optional): Google Places type of the venue. (See google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
`supported types <https://developers.google.com/places/web-service/supported_types>`_.) `supported types <https://developers.google.com/maps/documentation/places/web-service\
/supported_types>`_.)
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Attributes: Attributes:

4
telegram/_inline/inlinekeyboardbutton.py
View file

@ -82,6 +82,10 @@ class InlineKeyboardButton(TelegramObject):
callback_data (:obj:`str` | :obj:`object`, optional): Data to be sent in a callback query callback_data (:obj:`str` | :obj:`object`, optional): Data to be sent in a callback query
to the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows to the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows
arbitrary callback data, anything can be passed. arbitrary callback data, anything can be passed.
Tip:
The value entered here will be available in :attr:`telegram.CallbackQuery.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

3
telegram/_inline/inlinequeryresultvenue.py
View file

@ -50,7 +50,8 @@ class InlineQueryResultVenue(InlineQueryResult):
"food/icecream".) "food/icecream".)
google_place_id (:obj:`str`, optional): Google Places identifier of the venue. google_place_id (:obj:`str`, optional): Google Places identifier of the venue.
google_place_type (:obj:`str`, optional): Google Places type of the venue. (See google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
`supported types <https://developers.google.com/places/web-service/supported_types>`_.) `supported types <https://developers.google.com/maps/documentation/places/web-service\
/supported_types>`_.)
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message. to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the

3
telegram/_inline/inputvenuemessagecontent.py
View file

@ -45,7 +45,8 @@ class InputVenueMessageContent(InputMessageContent):
"food/icecream".) "food/icecream".)
google_place_id (:obj:`str`, optional): Google Places identifier of the venue. google_place_id (:obj:`str`, optional): Google Places identifier of the venue.
google_place_type (:obj:`str`, optional): Google Places type of the venue. (See google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
`supported types <https://developers.google.com/places/web-service/supported_types>`_.) `supported types <https://developers.google.com/maps/documentation/places/web-service\
/supported_types>`_.)
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Attributes: Attributes:

111
telegram/_message.py
View file

@ -789,9 +789,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -853,9 +852,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -912,9 +910,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -971,9 +968,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1022,9 +1018,9 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the media group is sent as an quote (:obj:`bool`, optional): If set to :obj:`True`, the media group is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, actual reply to this message. If ``reply_to_message_id`` is passed, this parameter
this parameter will be ignored. Default: :obj:`True` in group chats and will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private
:obj:`False` in private chats. chats.
Returns: Returns:
List[:class:`telegram.Message`]: An array of the sent Messages. List[:class:`telegram.Message`]: An array of the sent Messages.
@ -1075,9 +1071,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the photo is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the photo is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
this parameter will be ignored. Default: :obj:`True` in group chats and ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
:obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1135,9 +1130,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the audio is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the audio is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
this parameter will be ignored. Default: :obj:`True` in group chats and ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
:obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1197,9 +1191,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the document is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the document is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1259,9 +1252,9 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the animation is sent as an quote (:obj:`bool`, optional): If set to :obj:`True`, the animation is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, actual reply to this message. If ``reply_to_message_id`` is passed, this parameter
this parameter will be ignored. Default: :obj:`True` in group chats and will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private
:obj:`False` in private chats. chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1315,9 +1308,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the sticker is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the sticker is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1372,9 +1364,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the video is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the video is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1433,9 +1424,9 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the video note is sent as an quote (:obj:`bool`, optional): If set to :obj:`True`, the video note is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, actual reply to this message. If ``reply_to_message_id`` is passed, this parameter
this parameter will be ignored. Default: :obj:`True` in group chats and will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private
:obj:`False` in private chats. chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1490,9 +1481,9 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the voice note is sent as an quote (:obj:`bool`, optional): If set to :obj:`True`, the voice note is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, actual reply to this message. If ``reply_to_message_id`` is passed, this parameter
this parameter will be ignored. Default: :obj:`True` in group chats and will be ignored. Default: :obj:`True` in group chats and :obj:`False` in private
:obj:`False` in private chats. chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1549,9 +1540,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the location is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the location is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1611,9 +1601,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the venue is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the venue is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1671,9 +1660,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the contact is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the contact is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1734,9 +1722,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the poll is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the poll is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
this parameter will be ignored. Default: :obj:`True` in group chats and ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
:obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1793,9 +1780,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the dice is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the dice is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -1873,9 +1859,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the game is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the game is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
in private chats.
.. versionadded:: 13.2 .. versionadded:: 13.2
@ -1955,9 +1940,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the invoice is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the invoice is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -2014,7 +1998,6 @@ class Message(TelegramObject):
"""Shortcut for:: """Shortcut for::
await bot.forward_message( await bot.forward_message(
chat_id=chat_id,
from_chat_id=update.effective_message.chat_id, from_chat_id=update.effective_message.chat_id,
message_id=update.effective_message.message_id, message_id=update.effective_message.message_id,
*args, *args,
@ -2125,7 +2108,6 @@ class Message(TelegramObject):
await bot.copy_message( await bot.copy_message(
chat_id=message.chat.id, chat_id=message.chat.id,
from_chat_id=from_chat_id,
message_id=message_id, message_id=message_id,
*args, *args,
**kwargs **kwargs
@ -2135,9 +2117,8 @@ class Message(TelegramObject):
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to :obj:`True`, the copy is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the copy is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, reply to this message. If ``reply_to_message_id`` is passed, this parameter will be
this parameter will be ignored. Default: :obj:`True` in group chats and ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
:obj:`False` in private chats.
.. versionadded:: 13.1 .. versionadded:: 13.1

3
telegram/ext/_application.py
View file

@ -675,7 +675,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
and :paramref:`key` are not provided, the webhook will be started directly on and :paramref:`key` are not provided, the webhook will be started directly on
``http://listen:port/url_path``, so SSL can be handled by another ``http://listen:port/url_path``, so SSL can be handled by another
application. Else, the webhook will be started on application. Else, the webhook will be started on
``https://listen:port/url_path``. Also calls :meth:`telegram.Bot.set_webhook` as required. ``https://listen:port/url_path``. Also calls :meth:`telegram.Bot.set_webhook` as
required.
If :attr:`post_init` is set, it will be called between :meth:`initialize` and If :attr:`post_init` is set, it will be called between :meth:`initialize` and
:meth:`telegram.ext.Updater.start_webhook`. :meth:`telegram.ext.Updater.start_webhook`.

2
telegram/ext/_applicationbuilder.py
View file

@ -750,7 +750,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]):
fetch updates from. Will also be used for the :attr:`telegram.ext.Application.updater`. fetch updates from. Will also be used for the :attr:`telegram.ext.Application.updater`.
If not called, a queue will be instantiated. If not called, a queue will be instantiated.
.. seealso:: :attr:`telegram.ext.Updater.update_queue` .. seealso:: :attr:`telegram.ext.Updater.update_queue`
Args: Args:
update_queue (:class:`asyncio.Queue`): The queue. update_queue (:class:`asyncio.Queue`): The queue.

34
telegram/ext/_basepersistence.py
View file

@ -26,7 +26,8 @@ from telegram.ext._utils.types import BD, CD, UD, CDCData, ConversationDict, Con
class PersistenceInput(NamedTuple): # skipcq: PYL-E0239 class PersistenceInput(NamedTuple): # skipcq: PYL-E0239
"""Convenience wrapper to group boolean input for :class:`BasePersistence`. """Convenience wrapper to group boolean input for the :paramref:`~BasePersistence.store_data`
parameter for :class:`BasePersistence`.
Args: Args:
bot_data (:obj:`bool`, optional): Whether the setting should be applied for ``bot_data``. bot_data (:obj:`bool`, optional): Whether the setting should be applied for ``bot_data``.
@ -123,7 +124,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
update_interval (:obj:`int` | :obj:`float`, optional): The update_interval (:obj:`int` | :obj:`float`, optional): The
:class:`~telegram.ext.Application` will update :class:`~telegram.ext.Application` will update
the persistence in regular intervals. This parameter specifies the time (in seconds) to the persistence in regular intervals. This parameter specifies the time (in seconds) to
wait between two consecutive runs of updating the persistence. Defaults to 60 seconds. wait between two consecutive runs of updating the persistence. Defaults to ``60``
seconds.
.. versionadded:: 20.0 .. versionadded:: 20.0
@ -186,9 +188,9 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
:obj:`dict`. In the latter case, the dictionary should produce values :obj:`dict`. In the latter case, the dictionary should produce values
corresponding to one of the following: corresponding to one of the following:
* :obj:`dict` - :obj:`dict`
* The type from :attr:`telegram.ext.ContextTypes.user_data` - The type from :attr:`telegram.ext.ContextTypes.user_data`
if :class:`telegram.ext.ContextTypes` is used. if :class:`telegram.ext.ContextTypes` is used.
.. versionchanged:: 20.0 .. versionchanged:: 20.0
This method may now return a :obj:`dict` instead of a :obj:`collections.defaultdict` This method may now return a :obj:`dict` instead of a :obj:`collections.defaultdict`
@ -205,9 +207,9 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
:obj:`dict`. In the latter case, the dictionary should produce values :obj:`dict`. In the latter case, the dictionary should produce values
corresponding to one of the following: corresponding to one of the following:
* :obj:`dict` - :obj:`dict`
* The type from :attr:`telegram.ext.ContextTypes.chat_data` - The type from :attr:`telegram.ext.ContextTypes.chat_data`
if :class:`telegram.ext.ContextTypes` is used. if :class:`telegram.ext.ContextTypes` is used.
.. versionchanged:: 20.0 .. versionchanged:: 20.0
This method may now return a :obj:`dict` instead of a :obj:`collections.defaultdict` This method may now return a :obj:`dict` instead of a :obj:`collections.defaultdict`
@ -224,9 +226,9 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
:obj:`dict`. In the latter case, the :obj:`dict` should produce values :obj:`dict`. In the latter case, the :obj:`dict` should produce values
corresponding to one of the following: corresponding to one of the following:
* :obj:`dict` - :obj:`dict`
* The type from :attr:`telegram.ext.ContextTypes.bot_data` - The type from :attr:`telegram.ext.ContextTypes.bot_data`
if :class:`telegram.ext.ContextTypes` are used. if :class:`telegram.ext.ContextTypes` are used.
Returns: Returns:
Dict[:obj:`int`, :obj:`dict` | :attr:`telegram.ext.ContextTypes.bot_data`]: Dict[:obj:`int`, :obj:`dict` | :attr:`telegram.ext.ContextTypes.bot_data`]:
@ -244,9 +246,9 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Changed this method into an :external:func:`~abc.abstractmethod`. Changed this method into an :external:func:`~abc.abstractmethod`.
Returns: Returns:
Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]],
Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]]: Dict[:obj:`str`, :obj:`str`]] | :obj:`None`: The restored metadata or :obj:`None`,
The restored metadata or :obj:`None`, if no data was stored. if no data was stored.
""" """
@abstractmethod @abstractmethod
@ -320,8 +322,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC):
Changed this method into an :external:func:`~abc.abstractmethod`. Changed this method into an :external:func:`~abc.abstractmethod`.
Args: Args:
data (Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ data (Tuple[List[Tuple[:obj:`str`, :obj:`float`, \
Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]]]): Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]] | :obj:`None`):
The relevant data to restore :class:`telegram.ext.CallbackDataCache`. The relevant data to restore :class:`telegram.ext.CallbackDataCache`.
""" """

10
telegram/ext/_callbackqueryhandler.py
View file

@ -72,11 +72,11 @@ class CallbackQueryHandler(BaseHandler[Update, CCT]):
objects as :paramref:`~telegram.InlineKeyboardButton.callback_data`, non-strings will objects as :paramref:`~telegram.InlineKeyboardButton.callback_data`, non-strings will
be accepted. To filter arbitrary objects you may pass: be accepted. To filter arbitrary objects you may pass:
* a callable, accepting exactly one argument, namely the - a callable, accepting exactly one argument, namely the
:attr:`telegram.CallbackQuery.data`. It must return :obj:`True` or :attr:`telegram.CallbackQuery.data`. It must return :obj:`True` or
:obj:`False`/:obj:`None` to indicate, whether the update should be handled. :obj:`False`/:obj:`None` to indicate, whether the update should be handled.
* a :obj:`type`. If :attr:`telegram.CallbackQuery.data` is an instance of that type - a :obj:`type`. If :attr:`telegram.CallbackQuery.data` is an instance of that type
(or a subclass), the update will be handled. (or a subclass), the update will be handled.
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.

7
telegram/ext/_commandhandler.py
View file

@ -46,7 +46,12 @@ class CommandHandler(BaseHandler[Update, CCT]):
in the filter argument. in the filter argument.
Note: Note:
* :class:`CommandHandler` does *not* handle (edited) channel posts. :class:`CommandHandler` does *not* handle (edited) channel posts and does *not* handle
commands that are part of a caption. Please use :class:`~telegram.ext.MessageHandler`
with a suitable combination of filters (e.g.
:attr:`telegram.ext.filters.UpdateType.CHANNEL_POSTS`,
:attr:`telegram.ext.filters.CAPTION` and :class:`telegram.ext.filters.Regex`) to handle
those messages.
Warning: Warning:
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

4
telegram/ext/_defaults.py
View file

@ -41,7 +41,7 @@ class Defaults:
allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message
should be sent even if the specified replied-to message is not found. should be sent even if the specified replied-to message is not found.
quote (:obj:`bool`, optional): If set to :obj:`True`, the reply is sent as an actual reply quote (:obj:`bool`, optional): If set to :obj:`True`, the reply is sent as an actual reply
to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will to the message. If ``reply_to_message_id`` is passed, this parameter will
be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats. be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
tzinfo (:obj:`tzinfo`, optional): A timezone to be used for all date(time) inputs tzinfo (:obj:`tzinfo`, optional): A timezone to be used for all date(time) inputs
appearing throughout PTB, i.e. if a timezone naive date(time) object is passed appearing throughout PTB, i.e. if a timezone naive date(time) object is passed
@ -173,7 +173,7 @@ class Defaults:
@property @property
def quote(self) -> Optional[bool]: def quote(self) -> Optional[bool]:
""":obj:`bool`: Optional. If set to :obj:`True`, the reply is sent as an actual reply """:obj:`bool`: Optional. If set to :obj:`True`, the reply is sent as an actual reply
to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will to the message. If ``reply_to_message_id`` is passed, this parameter will
be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats. be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
""" """
return self._quote return self._quote

2
telegram/ext/_dictpersistence.py
View file

@ -58,7 +58,7 @@ class DictPersistence(BasePersistence):
bot_data on creating this persistence. Default is ``""``. bot_data on creating this persistence. Default is ``""``.
conversations_json (:obj:`str`, optional): JSON string that will be used to reconstruct conversations_json (:obj:`str`, optional): JSON string that will be used to reconstruct
conversation on creating this persistence. Default is ``""``. conversation on creating this persistence. Default is ``""``.
callback_data_json (:obj:`str`, optional): Json string that will be used to reconstruct callback_data_json (:obj:`str`, optional): JSON string that will be used to reconstruct
callback_data on creating this persistence. Default is ``""``. callback_data on creating this persistence. Default is ``""``.
.. versionadded:: 13.6 .. versionadded:: 13.6

20
telegram/ext/_jobqueue.py
View file

@ -44,7 +44,7 @@ class JobQueue:
scheduler (:class:`apscheduler.schedulers.asyncio.AsyncIOScheduler`): The scheduler. scheduler (:class:`apscheduler.schedulers.asyncio.AsyncIOScheduler`): The scheduler.
.. versionchanged:: 20.0 .. versionchanged:: 20.0
Use :class:`~apscheduler.schedulers.asyncio.AsyncIOScheduler` instead of Uses :class:`~apscheduler.schedulers.asyncio.AsyncIOScheduler` instead of
:class:`~apscheduler.schedulers.background.BackgroundScheduler` :class:`~apscheduler.schedulers.background.BackgroundScheduler`
@ -248,13 +248,13 @@ class JobQueue:
tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the
default timezone of the bot will be used. default timezone of the bot will be used.
Defaults to ``interval`` Defaults to :paramref:`interval`
last (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | \ last (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | \
:obj:`datetime.datetime` | :obj:`datetime.time`, optional): :obj:`datetime.datetime` | :obj:`datetime.time`, optional):
Latest possible time for the job to run. This parameter will be interpreted Latest possible time for the job to run. This parameter will be interpreted
depending on its type. See ``first`` for details. depending on its type. See :paramref:`first` for details.
If ``last`` is :obj:`datetime.datetime` or :obj:`datetime.time` type If :paramref:`last` is :obj:`datetime.datetime` or :obj:`datetime.time` type
and ``last.tzinfo`` is :obj:`None`, the default timezone of the bot will be and ``last.tzinfo`` is :obj:`None`, the default timezone of the bot will be
assumed. assumed.
@ -329,8 +329,8 @@ class JobQueue:
"""Creates a new :class:`Job` that runs on a monthly basis and adds it to the queue. """Creates a new :class:`Job` that runs on a monthly basis and adds it to the queue.
.. versionchanged:: 20.0 .. versionchanged:: 20.0
The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day`` The ``day_is_strict`` argument was removed. Instead one can now pass ``-1`` to the
parameter to have the job run on the last day of the month. :paramref:`day` parameter to have the job run on the last day of the month.
Args: Args:
callback (:term:`coroutine function`): The callback function that should be executed by callback (:term:`coroutine function`): The callback function that should be executed by
@ -341,9 +341,9 @@ class JobQueue:
when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
(``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used. (``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used.
day (:obj:`int`): Defines the day of the month whereby the job would run. It should day (:obj:`int`): Defines the day of the month whereby the job would run. It should
be within the range of 1 and 31, inclusive. If a month has fewer days than this be within the range of ``1`` and ``31``, inclusive. If a month has fewer days than
number, the job will not run in this month. Passing -1 leads to the job running on this number, the job will not run in this month. Passing ``-1`` leads to the job
the last day of the month. running on the last day of the month.
data (:obj:`object`, optional): Additional data needed for the callback function. data (:obj:`object`, optional): Additional data needed for the callback function.
Can be accessed through :attr:`Job.data` in the callback. Defaults to Can be accessed through :attr:`Job.data` in the callback. Defaults to
:obj:`None`. :obj:`None`.
@ -535,7 +535,7 @@ class JobQueue:
async def start(self) -> None: async def start(self) -> None:
# this method async just in case future versions need that # this method async just in case future versions need that
"""Starts the job_queue.""" """Starts the :class:`~telegram.ext.JobQueue`."""
if not self.scheduler.running: if not self.scheduler.running:
self.scheduler.start() self.scheduler.start()

6
telegram/ext/_picklepersistence.py
View file

@ -343,9 +343,9 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
.. versionadded:: 13.6 .. versionadded:: 13.6
Returns: Returns:
Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]],
Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]]: Dict[:obj:`str`, :obj:`str`]] | :obj:`None`: The restored metadata or :obj:`None`,
The restored metadata or :obj:`None`, if no data was stored. if no data was stored.
""" """
if self.callback_data: if self.callback_data:
pass pass

4
telegram/ext/_updater.py
View file

@ -373,9 +373,9 @@ class Updater(AbstractAsyncContextManager):
""" """
Starts a small http server to listen for updates via webhook. If :paramref:`cert` Starts a small http server to listen for updates via webhook. If :paramref:`cert`
and :paramref:`key` are not provided, the webhook will be started directly on and :paramref:`key` are not provided, the webhook will be started directly on
http://listen:port/url_path, so SSL can be handled by another ``http://listen:port/url_path``, so SSL can be handled by another
application. Else, the webhook will be started on application. Else, the webhook will be started on
https://listen:port/url_path. Also calls :meth:`telegram.Bot.set_webhook` as required. ``https://listen:port/url_path``. Also calls :meth:`telegram.Bot.set_webhook` as required.
.. 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