From 11007c17154e874716cdb99f6fdcd04c1724c8df Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Thu, 9 Jun 2022 17:08:54 +0200 Subject: [PATCH] Documentation Improvements (#3010, #3007, #3012, #3067, #3081, #3082) Co-authored-by: KnorpelSenf Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Poolitzer Co-authored-by: Adi <71205439+Aditya-Rajgor@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/CONTRIBUTING.rst | 16 +- .github/workflows/docs-linkcheck.yml | 29 +++ .github/workflows/docs.yml | 5 - .readthedocs.yml | 6 +- CHANGES.rst | 8 +- CODE_OF_CONDUCT.rst | 2 +- README.rst | 18 +- README_RAW.rst | 16 +- docs/requirements-docs.txt | 9 +- docs/source/conf.py | 232 ++++--------------- docs/source/telegram.ext.rst | 14 +- docs/source/telegram.rst | 58 ++--- examples/README.md | 58 ++--- examples/inlinebot.py | 2 + setup.py | 4 +- telegram/_bot.py | 44 ++-- telegram/_callbackquery.py | 93 ++++---- telegram/_chat.py | 6 +- telegram/_chatmember.py | 1 + telegram/_chatmemberupdated.py | 2 +- telegram/_files/venue.py | 3 +- telegram/_inline/inlinekeyboardbutton.py | 4 + telegram/_inline/inlinequeryresultvenue.py | 3 +- telegram/_inline/inputvenuemessagecontent.py | 3 +- telegram/_message.py | 111 ++++----- telegram/ext/_application.py | 3 +- telegram/ext/_applicationbuilder.py | 2 +- telegram/ext/_basepersistence.py | 34 +-- telegram/ext/_callbackqueryhandler.py | 10 +- telegram/ext/_commandhandler.py | 7 +- telegram/ext/_defaults.py | 4 +- telegram/ext/_dictpersistence.py | 2 +- telegram/ext/_jobqueue.py | 20 +- telegram/ext/_picklepersistence.py | 6 +- telegram/ext/_updater.py | 4 +- 35 files changed, 362 insertions(+), 477 deletions(-) create mode 100644 .github/workflows/docs-linkcheck.yml diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 03044145b..a8cc589fa 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -263,19 +263,19 @@ break the API classes. For example: 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 .. _`Telegram group`: https://telegram.me/pythontelegrambotgroup -.. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/ -.. _`sphinx`: http://sphinx-doc.org -.. _`Google Python Style Guide`: http://google.github.io/styleguide/pyguide.html +.. _`PEP 8 Style Guide`: https://peps.python.org/pep-0008/ +.. _`sphinx`: https://www.sphinx-doc.org/en/master +.. _`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 -.. _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 .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html .. _`Black`: https://black.readthedocs.io/en/stable/index.html -.. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html -.. _`RTD`: https://python-telegram-bot.readthedocs.io/ -.. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes +.. _`popular editors`: https://black.readthedocs.io/en/stable/integrations/editors.html +.. _`RTD`: https://docs.python-telegram-bot.org/ +.. _`RTD build`: https://docs.python-telegram-bot.org/en/doc-fixes .. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html .. _`section`: #documenting diff --git a/.github/workflows/docs-linkcheck.yml b/.github/workflows/docs-linkcheck.yml new file mode 100644 index 000000000..531210969 --- /dev/null +++ b/.github/workflows/docs-linkcheck.yml @@ -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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b620dd903..d674837f2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,12 +3,10 @@ on: pull_request: branches: - master - - v14 - doc-fixes push: branches: - master - - v14 - doc-fixes jobs: @@ -22,9 +20,6 @@ jobs: fail-fast: False steps: - uses: actions/checkout@v3 - - name: Initialize vendored libs - run: - git submodule update --init --recursive - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v3 with: diff --git a/.readthedocs.yml b/.readthedocs.yml index 41af24d63..7a2c8f32a 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -15,8 +15,12 @@ formats: # Optionally set the version of Python and requirements required to build your docs python: - version: 3 install: - method: pip path: . - requirements: docs/requirements-docs.txt + +build: + os: ubuntu-20.04 + tools: + python: "3" # latest stable cpython version diff --git a/CHANGES.rst b/CHANGES.rst index 7264ea7e3..f3eb2de8c 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -72,9 +72,9 @@ New Features: by `DonalDuck004 `__) - Add Method ``drop_chat/user_data`` to ``Dispatcher`` and Persistence (`#2852 `__) -- Add methods ``ChatPermissions.{all, no}_permissions`` ([#2948] +- Add methods ``ChatPermissions.{all, no}_permissions`` (`#2948 `__) - Full Support for API 6.0 - (`#2956 `__)(https://github.com/python-telegram-bot/python-telegram-bot/pull/2948)) + (`#2956 `__) - Add Python 3.10 to Test Suite (`#2968 `__) @@ -1520,7 +1520,7 @@ Changes - 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 .. _`#806`: https://github.com/python-telegram-bot/python-telegram-bot/pull/806 .. _`#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 - Almost complete recode of ``Dispatcher`` -- Please read the `Transistion Guide to 4.0 `_ +- Please read the `Transistion Guide to 4.0 `_ **2016-03-22** diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst index 6920482dc..5a1d6d26f 100644 --- a/CODE_OF_CONDUCT.rst +++ b/CODE_OF_CONDUCT.rst @@ -49,4 +49,4 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai Attribution =========== -This Code of Conduct is adapted from the `Contributor Covenant `_, version 1.4, available at `http://contributor-covenant.org/version/1/4 `_. +This Code of Conduct is adapted from the `Contributor Covenant `_, version 1.4, available at `https://www.contributor-covenant.org/version/1/4 `_. diff --git a/README.rst b/README.rst index 6ee6a6b6f..e64417519 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ .. 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 :target: https://python-telegram-bot.org :alt: python-telegram-bot Logo @@ -23,7 +23,7 @@ :alt: PyPi Package Monthly Download .. 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 .. 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/ :alt: Github Actions workflow -.. image:: https://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 +.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg + :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: Code coverage -.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg - :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot +.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg + :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :alt: Median time to resolve an issue .. 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&utm_medium=referral&utm_content=python-telegram-bot/python-telegram-bot&utm_campaign=Badge_Grade + :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: Code quality: Codacy .. 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: -* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 `_ library. Use this, if you want to use Telegram Passport related functionality. +* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 `_ 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. Quick Start @@ -148,7 +148,7 @@ Moreover, the `Tutorial: Your first Bot `_ is the technical reference for ``python-telegram-bot``. +- The `package documentation `_ is the technical reference for ``python-telegram-bot``. It contains descriptions of all available classes, modules, methods and arguments. - The `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 `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. diff --git a/README_RAW.rst b/README_RAW.rst index 92dd43ec1..dd22b96c9 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -23,7 +23,7 @@ :alt: PyPi Package Monthly Download .. 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 .. 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/ :alt: Github Actions workflow -.. image:: https://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 +.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg + :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: Code coverage -.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg - :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot +.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg + :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :alt: Median time to resolve an issue .. 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&utm_medium=referral&utm_content=python-telegram-bot/python-telegram-bot&utm_campaign=Badge_Grade + :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: Code quality: Codacy .. 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: -* ``pip install python-telegram-bot[passport]`` installs the `cryptography `_ library. Use this, if you want to use Telegram Passport related functionality. +* ``pip install python-telegram-bot[passport]`` installs the `cryptography `_ library. Use this, if you want to use Telegram Passport related functionality. * ``pip install python-telegram-bot[socks]`` installs the `PySocks `_ library. Use this, if you want to work behind a Socks5 server. Quick Start @@ -145,7 +145,7 @@ Our Wiki contains an `Introduction to the API `_ is the technical reference for ``python-telegram-bot``. +- The `package documentation `_ is the technical reference for ``python-telegram-bot``. It contains descriptions of all available classes, modules, methods and arguments. - The `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 `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 9c5e03c38..5bd714ec3 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,7 +1,4 @@ -sphinx==4.5.0 +sphinx==5.0.1 sphinx-pypi-upload -furo==2022.04.07 -# Can be replaced with a sphinx-paramlinks==... dependency once a version is released that -# includes the commit mentioned below and maybe even -# https://github.com/sqlalchemyorg/sphinx-paramlinks/pull/14 -git+https://github.com/sqlalchemyorg/sphinx-paramlinks.git@acedb03149e3f87ff599174b033754c2f58f1c95 \ No newline at end of file +furo==2022.6.4 +sphinx-paramlinks==0.5.4 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index a421560d1..bf05af76d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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 os import re @@ -32,6 +19,19 @@ from sphinx.util import logging sys.path.insert(0, os.path.abspath("../..")) # -- 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. needs_sphinx = "4.5.0" @@ -53,76 +53,49 @@ intersphinx_mapping = { "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 # and we document the types anyway autodoc_typehints = "none" -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - # Fail on warnings & unresolved references etc nitpicky = True # Paramlink style paramlinks_hyperlink_param = "name" +# 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. pygments_style = "sphinx" @@ -130,16 +103,9 @@ pygments_style = "sphinx" # Decides the language used for syntax highlighting of code blocks. 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. todo_include_todos = False - # -- Options for HTML output ---------------------------------------------- # 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 # " v documentation". html_title = f"python-telegram-bot
v{version}" -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - # The name of an image file (relative to this directory) to place at the top # of the sidebar. html_logo = "ptb-logo_1024.png" @@ -251,72 +211,16 @@ html_favicon = "ptb-logo_1024.ico" # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] - html_css_files = ["style_external_link.css"] - -# 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 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' +html_permalinks_icon = "¶" # Furo's default permalink icon is `#`` which doesn't look great imo. # Output file base name for HTML help builder. htmlhelp_basename = "python-telegram-bot-doc" +# 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 --------------------------------------------- latex_elements = { @@ -343,32 +247,12 @@ latex_documents = [ # the title page. 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 --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). 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 ------------------------------------------- @@ -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 -------------------------------------------------------- # get the sphinx(!) logger diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst index 3f6ceb609..1b8dc8ea5 100644 --- a/docs/source/telegram.ext.rst +++ b/docs/source/telegram.ext.rst @@ -3,16 +3,16 @@ telegram.ext package .. toctree:: - telegram.ext.extbot - telegram.ext.applicationbuilder telegram.ext.application + telegram.ext.applicationbuilder telegram.ext.applicationhandlerstop - telegram.ext.updater telegram.ext.callbackcontext - telegram.ext.job - telegram.ext.jobqueue telegram.ext.contexttypes telegram.ext.defaults + telegram.ext.extbot + telegram.ext.job + telegram.ext.jobqueue + telegram.ext.updater Handlers -------- @@ -26,9 +26,9 @@ Handlers telegram.ext.choseninlineresulthandler telegram.ext.commandhandler telegram.ext.conversationhandler + telegram.ext.filters telegram.ext.inlinequeryhandler telegram.ext.messagehandler - telegram.ext.filters telegram.ext.pollanswerhandler telegram.ext.pollhandler telegram.ext.precheckoutqueryhandler @@ -44,9 +44,9 @@ Persistence .. toctree:: telegram.ext.basepersistence + telegram.ext.dictpersistence telegram.ext.persistenceinput telegram.ext.picklepersistence - telegram.ext.dictpersistence Arbitrary Callback Data ----------------------- diff --git a/docs/source/telegram.rst b/docs/source/telegram.rst index 9ddcbaecb..76d20257e 100644 --- a/docs/source/telegram.rst +++ b/docs/source/telegram.rst @@ -17,13 +17,13 @@ Available Types telegram.bot telegram.botcommand telegram.botcommandscope - telegram.botcommandscopedefault - telegram.botcommandscopeallprivatechats - telegram.botcommandscopeallgroupchats telegram.botcommandscopeallchatadministrators + telegram.botcommandscopeallgroupchats + telegram.botcommandscopeallprivatechats telegram.botcommandscopechat telegram.botcommandscopechatadministrators telegram.botcommandscopechatmember + telegram.botcommandscopedefault telegram.callbackquery telegram.chat telegram.chatadministratorrights @@ -31,12 +31,12 @@ Available Types telegram.chatjoinrequest telegram.chatlocation telegram.chatmember - telegram.chatmemberowner telegram.chatmemberadministrator - telegram.chatmembermember - telegram.chatmemberrestricted - telegram.chatmemberleft telegram.chatmemberbanned + telegram.chatmemberleft + telegram.chatmembermember + telegram.chatmemberowner + telegram.chatmemberrestricted telegram.chatmemberupdated telegram.chatpermissions telegram.chatphoto @@ -64,15 +64,15 @@ Available Types telegram.menubuttonwebapp telegram.message telegram.messageautodeletetimerchanged - telegram.messageid telegram.messageentity + telegram.messageid telegram.photosize telegram.poll telegram.pollanswer telegram.polloption telegram.proximityalerttriggered - telegram.replykeyboardremove telegram.replykeyboardmarkup + telegram.replykeyboardremove telegram.sentwebappmessage telegram.telegramobject telegram.update @@ -95,15 +95,16 @@ Stickers .. toctree:: + telegram.maskposition telegram.sticker telegram.stickerset - telegram.maskposition Inline Mode ----------- .. toctree:: + telegram.choseninlineresult telegram.inlinequery telegram.inlinequeryresult telegram.inlinequeryresultarticle @@ -132,29 +133,28 @@ Inline Mode telegram.inputvenuemessagecontent telegram.inputcontactmessagecontent telegram.inputinvoicemessagecontent - telegram.choseninlineresult Payments -------- .. toctree:: - telegram.labeledprice telegram.invoice - telegram.shippingaddress + telegram.labeledprice telegram.orderinfo - telegram.shippingoption - telegram.successfulpayment - telegram.shippingquery telegram.precheckoutquery + telegram.shippingaddress + telegram.shippingoption + telegram.shippingquery + telegram.successfulpayment Games ----- .. toctree:: - telegram.game telegram.callbackgame + telegram.game telegram.gamehighscore Passport @@ -162,25 +162,25 @@ Passport .. toctree:: + telegram.credentials + telegram.datacredentials + telegram.encryptedcredentials + telegram.encryptedpassportelement + telegram.filecredentials + telegram.iddocumentdata + telegram.passportdata telegram.passportelementerror + telegram.passportelementerrordatafield telegram.passportelementerrorfile telegram.passportelementerrorfiles - telegram.passportelementerrorreverseside telegram.passportelementerrorfrontside - telegram.passportelementerrordatafield + telegram.passportelementerrorreverseside telegram.passportelementerrorselfie telegram.passportelementerrortranslationfile telegram.passportelementerrortranslationfiles telegram.passportelementerrorunspecified - telegram.credentials - telegram.datacredentials - telegram.securedata - telegram.securevalue - telegram.filecredentials - telegram.iddocumentdata + telegram.passportfile telegram.personaldetails telegram.residentialaddress - telegram.passportdata - telegram.passportfile - telegram.encryptedpassportelement - telegram.encryptedcredentials + telegram.securedata + telegram.securevalue diff --git a/examples/README.md b/examples/README.md index 697bb0cc1..1afaeec4d 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,71 +1,71 @@ # 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/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. -### [`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. -### [`timerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/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). +### [`timerbot.py`](timerbot.py) +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) -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). +### [`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://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) -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! +### [`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](conversationbot2.png) for this one, too! -### [`nestedconversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/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! +### [`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](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. -### [`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). -### [`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. -### [`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. -### [`inlinebot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/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). +### [`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://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. -### [`passportbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/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. +### [`passportbot.py`](passportbot.py) +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) -A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather). +### [`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://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. -### [`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. -### [`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. -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. 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. ### [`customwebhookbot.py`](customwebhookbot.py) 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. ## 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. diff --git a/examples/inlinebot.py b/examples/inlinebot.py index 1b11fe948..901b69e09 100644 --- a/examples/inlinebot.py +++ b/examples/inlinebot.py @@ -3,6 +3,8 @@ # 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 the Application and registered at their respective places. Then, the bot is started and runs until we press Ctrl-C on the command line. diff --git a/setup.py b/setup.py index 4fab0107a..7b9e72ffb 100644 --- a/setup.py +++ b/setup.py @@ -56,11 +56,11 @@ def get_setup_kwargs(raw=False): 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 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", "Source Code": "https://github.com/python-telegram-bot/python-telegram-bot", "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}/", keywords="python telegram bot api wrapper", diff --git a/telegram/_bot.py b/telegram/_bot.py index b6b9c0325..ebc6aa5dd 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -1230,7 +1230,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers. 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')`` Args: @@ -1334,11 +1334,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager): changed in the future. 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')`` - * ``thumb`` will be ignored for small video files, for which Telegram can easily - generate thumb nails. However, this behaviour is undocumented and might be changed - by Telegram. + * :paramref:`thumb` will be ignored for small video files, for which Telegram can + easily generate thumbnails. However, this behaviour is undocumented and might be + changed by Telegram. Args: 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. 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')`` - * ``thumb`` will be ignored for small video files, for which Telegram can easily - generate thumb nails. However, this behaviour is undocumented and might be changed - by Telegram. + * :paramref:`thumb` will be ignored for small video files, for which Telegram can + easily generate thumbnails. However, this behaviour is undocumented and might be + changed by Telegram. Args: 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. 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')``. - * To use this method, the file must have the type ``audio/ogg`` and be no more than 1MB - in size. 1-20MB voice notes will be sent as files. + * To use this method, the file must have the type :mimetype:`audio/ogg` and be no more + than ``1MB`` in size. ``1-20MB`` voice notes will be sent as files. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -2272,10 +2272,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Note: * You can either supply :paramref:`venue`, or :paramref:`latitude`, - :paramref:`longitude`, - :paramref:title` and :paramref:address` and optionally :paramref:`foursquare_id` and - :paramref:`foursquare_type` or optionally :paramref:`google_place_id` and - :paramref:`google_place_type`. + :paramref:`longitude`, :paramref:`title` and :paramref:`address` and optionally + :paramref:`foursquare_id` and :paramref:`foursquare_type` or optionally + :paramref:`google_place_id` and :paramref:`google_place_type`. * Foursquare details and Google Place details are mutually exclusive. However, this behaviour is undocumented and might be changed by Telegram. @@ -2293,7 +2292,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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 `supported types \ - `_.) + `_.) disable_notification (:obj:`bool`, optional): Sends the message silently. Users will receive a notification with no sound. protect_content (:obj:`bool`, optional): Protects the contents of the sent message from @@ -3811,7 +3810,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): 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/. 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: The certificate argument should be a file from disk ``open(filename, 'rb')``. @@ -3821,7 +3820,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): integration. certificate (:term:`file object`): Upload your public key certificate so that the root certificate in use can be checked. See our self-signed guide for details. - (https://goo.gl/rw7w6Y) + (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 webhook requests instead of the IP address resolved through DNS. max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS @@ -4140,7 +4140,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): ) -> int: """Use this method to get the number of members in a chat. - .. versionadded:: 13.7 + .. versionadded:: 13.7 Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -6202,8 +6202,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): times). Note: - The png_sticker argument can be either a file_id, an URL or a file from disk - ``open(filename, 'rb')`` + The :paramref:`png_sticker` argument can be either a file_id, an URL or a file from + disk ``open(filename, 'rb')`` Args: user_id (:obj:`int`): User identifier of sticker file owner. diff --git a/telegram/_callbackquery.py b/telegram/_callbackquery.py index ece1d3425..111cc6f7e 100644 --- a/telegram/_callbackquery.py +++ b/telegram/_callbackquery.py @@ -65,7 +65,6 @@ class CallbackQuery(TelegramObject): .. versionadded:: 13.6 - Args: id (:obj:`str`): Unique identifier for this query. from_user (:class:`telegram.User`): Sender. @@ -74,8 +73,8 @@ class CallbackQuery(TelegramObject): 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 if the message is too old. - data (:obj:`str`, optional): Data associated with the callback button. Be aware that a bad - client can send arbitrary data in this field. + data (:obj:`str`, optional): Data associated with the callback button. Be aware that the + 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 mode, that originated the query. 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 originated the query. 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 mode, that originated the query. game_short_name (:obj:`str`): Optional. Short name of a Game to be returned. @@ -199,12 +202,13 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.edit_text(text, *args, **kwargs) + await update.callback_query.message.edit_text(*args, **kwargs) or:: - bot.edit_message_text(text, inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs) + await bot.edit_message_text( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs, + ) For the documentation of the arguments, please see :meth:`telegram.Bot.edit_message_text` and :meth:`telegram.Message.edit_text`. @@ -258,13 +262,13 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.edit_caption(caption, *args, **kwargs) + await update.callback_query.message.edit_caption(*args, **kwargs) or:: - bot.edit_message_caption(caption=caption - inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs) + await bot.edit_message_caption( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs, + ) For the documentation of the arguments, please see :meth:`telegram.Bot.edit_message_caption` and :meth:`telegram.Message.edit_caption`. @@ -313,19 +317,12 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.edit_reply_markup( - reply_markup=reply_markup, - *args, - **kwargs - ) + await update.callback_query.message.edit_reply_markup(*args, **kwargs) or:: - bot.edit_message_reply_markup - inline_message_id=update.callback_query.inline_message_id, - reply_markup=reply_markup, - *args, - **kwargs + await bot.edit_message_reply_markup( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs ) For the documentation of the arguments, please see @@ -371,12 +368,13 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.edit_media(*args, **kwargs) + await update.callback_query.message.edit_media(*args, **kwargs) or:: - bot.edit_message_media(inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs) + await bot.edit_message_media( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs + ) For the documentation of the arguments, please see :meth:`telegram.Bot.edit_message_media` and :meth:`telegram.Message.edit_media`. @@ -427,13 +425,12 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.edit_live_location(*args, **kwargs) + await update.callback_query.message.edit_live_location(*args, **kwargs) or:: - bot.edit_message_live_location( - inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs + await bot.edit_message_live_location( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs ) For the documentation of the arguments, please see @@ -490,13 +487,12 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.stop_live_location(*args, **kwargs) + await update.callback_query.message.stop_live_location(*args, **kwargs) or:: - bot.stop_message_live_location( - inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs + await bot.stop_message_live_location( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs ) For the documentation of the arguments, please see @@ -544,12 +540,13 @@ class CallbackQuery(TelegramObject): ) -> Union[Message, bool]: """Shortcut for either:: - update.callback_query.message.set_game_score(*args, **kwargs) + await update.callback_query.message.set_game_score(*args, **kwargs) or:: - bot.set_game_score(inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs) + await bot.set_game_score( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs + ) For the documentation of the arguments, please see :meth:`telegram.Bot.set_game_score` and :meth:`telegram.Message.set_game_score`. @@ -598,12 +595,13 @@ class CallbackQuery(TelegramObject): ) -> List["GameHighScore"]: """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:: - bot.get_game_high_scores(inline_message_id=update.callback_query.inline_message_id, - *args, **kwargs) + await bot.get_game_high_scores( + inline_message_id=update.callback_query.inline_message_id, *args, **kwargs + ) For the documentation of the arguments, please see :meth:`telegram.Bot.get_game_high_scores` and @@ -645,10 +643,9 @@ class CallbackQuery(TelegramObject): ) -> bool: """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 - :meth:`telegram.Message.delete`. + For the documentation of the arguments, please see :meth:`telegram.Message.delete`. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -674,10 +671,9 @@ class CallbackQuery(TelegramObject): ) -> bool: """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 - :meth:`telegram.Message.pin`. + For the documentation of the arguments, please see :meth:`telegram.Message.pin`. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -703,10 +699,9 @@ class CallbackQuery(TelegramObject): ) -> bool: """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 - :meth:`telegram.Message.unpin`. + For the documentation of the arguments, please see :meth:`telegram.Message.unpin`. Returns: :obj:`bool`: On success, :obj:`True` is returned. @@ -740,16 +735,14 @@ class CallbackQuery(TelegramObject): ) -> "MessageId": """Shortcut for:: - update.callback_query.message.copy( - chat_id, + await update.callback_query.message.copy( from_chat_id=update.message.chat_id, message_id=update.message.message_id, *args, **kwargs ) - For the documentation of the arguments, please see - :meth:`telegram.Message.copy`. + For the documentation of the arguments, please see :meth:`telegram.Message.copy`. Returns: :class:`telegram.MessageId`: On success, returns the MessageId of the sent message. diff --git a/telegram/_chat.py b/telegram/_chat.py index 8e6645588..a4a0721e2 100644 --- a/telegram/_chat.py +++ b/telegram/_chat.py @@ -81,10 +81,10 @@ class Chat(TelegramObject): type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`, :attr:`SUPERGROUP` or :attr:`CHANNEL`. title (:obj:`str`, optional): Title, for supergroups, channels and group chats. - username(:obj:`str`, optional): Username, for private chats, supergroups and channels if + username (:obj:`str`, optional): Username, for private chats, supergroups and channels if available. - first_name(:obj:`str`, optional): First name of the other party in a private chat. - last_name(:obj:`str`, optional): Last name of the other party in a private chat. + first_name (:obj:`str`, optional): First name of the other party in a private chat. + last_name (:obj:`str`, optional): Last name of the other party in a private chat. photo (:class:`telegram.ChatPhoto`, optional): Chat photo. Returned only in :meth:`telegram.Bot.get_chat`. bio (:obj:`str`, optional): Bio of the other party in a private chat. Returned only in diff --git a/telegram/_chatmember.py b/telegram/_chatmember.py index 0cd45cfcc..387cefa4a 100644 --- a/telegram/_chatmember.py +++ b/telegram/_chatmember.py @@ -45,6 +45,7 @@ class ChatMember(TelegramObject): considered equal, if their :attr:`user` and :attr:`status` are equal. .. versionchanged:: 20.0 + * 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`. Therefore, most of the arguments and attributes were removed and you should no longer diff --git a/telegram/_chatmemberupdated.py b/telegram/_chatmemberupdated.py index 622833aef..26de5b00e 100644 --- a/telegram/_chatmemberupdated.py +++ b/telegram/_chatmemberupdated.py @@ -166,7 +166,7 @@ class ChatMemberUpdated(TelegramObject): Returns: 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 # user.to_dict() is unhashable, so that needs some special casing further down diff --git a/telegram/_files/venue.py b/telegram/_files/venue.py index 630ac9cc9..ca30d3cc7 100644 --- a/telegram/_files/venue.py +++ b/telegram/_files/venue.py @@ -47,7 +47,8 @@ class Venue(TelegramObject): "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".) 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 - `supported types `_.) + `supported types `_.) **kwargs (:obj:`dict`): Arbitrary keyword arguments. Attributes: diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index 79cdfbf5b..a2cd5990f 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -82,6 +82,10 @@ class InlineKeyboardButton(TelegramObject): callback_data (:obj:`str` | :obj:`object`, optional): Data to be sent in a callback query to the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows arbitrary callback data, anything can be passed. + + Tip: + The value entered here will be available in :attr:`telegram.CallbackQuery.data`. + web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App `_ that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user diff --git a/telegram/_inline/inlinequeryresultvenue.py b/telegram/_inline/inlinequeryresultvenue.py index 8d697ba14..5449c92c6 100644 --- a/telegram/_inline/inlinequeryresultvenue.py +++ b/telegram/_inline/inlinequeryresultvenue.py @@ -50,7 +50,8 @@ class InlineQueryResultVenue(InlineQueryResult): "food/icecream".) 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 - `supported types `_.) + `supported types `_.) reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the diff --git a/telegram/_inline/inputvenuemessagecontent.py b/telegram/_inline/inputvenuemessagecontent.py index e5b8e91d2..83ed9d608 100644 --- a/telegram/_inline/inputvenuemessagecontent.py +++ b/telegram/_inline/inputvenuemessagecontent.py @@ -45,7 +45,8 @@ class InputVenueMessageContent(InputMessageContent): "food/icecream".) 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 - `supported types `_.) + `supported types `_.) **kwargs (:obj:`dict`): Arbitrary keyword arguments. Attributes: diff --git a/telegram/_message.py b/telegram/_message.py index 9fec8d65e..d3fa198f6 100644 --- a/telegram/_message.py +++ b/telegram/_message.py @@ -789,9 +789,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -853,9 +852,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -912,9 +910,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -971,9 +968,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1022,9 +1018,9 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + actual reply to this 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. Returns: List[:class:`telegram.Message`]: An array of the sent Messages. @@ -1075,9 +1071,8 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1135,9 +1130,8 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1197,9 +1191,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1259,9 +1252,9 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + actual reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1315,9 +1308,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1372,9 +1364,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1433,9 +1424,9 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + actual reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1490,9 +1481,9 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + actual reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1549,9 +1540,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1611,9 +1601,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1671,9 +1660,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in - private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1734,9 +1722,8 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1793,9 +1780,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` - in private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -1873,9 +1859,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` - in private chats. + reply to this 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. .. versionadded:: 13.2 @@ -1955,9 +1940,8 @@ class Message(TelegramObject): Keyword Args: 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 - parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` - in private chats. + reply to this 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. Returns: :class:`telegram.Message`: On success, instance representing the message posted. @@ -2014,7 +1998,6 @@ class Message(TelegramObject): """Shortcut for:: await bot.forward_message( - chat_id=chat_id, from_chat_id=update.effective_message.chat_id, message_id=update.effective_message.message_id, *args, @@ -2125,7 +2108,6 @@ class Message(TelegramObject): await bot.copy_message( chat_id=message.chat.id, - from_chat_id=from_chat_id, message_id=message_id, *args, **kwargs @@ -2135,9 +2117,8 @@ class Message(TelegramObject): Keyword Args: 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``, - this parameter will be ignored. Default: :obj:`True` in group chats and - :obj:`False` in private chats. + reply to this 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. .. versionadded:: 13.1 diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index 58a66098c..6ba64bfd4 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -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 ``http://listen:port/url_path``, so SSL can be handled by another application. Else, the webhook will be started on - ``https://listen:port/url_path``. Also calls :meth:`telegram.Bot.set_webhook` as required. + ``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 :meth:`telegram.ext.Updater.start_webhook`. diff --git a/telegram/ext/_applicationbuilder.py b/telegram/ext/_applicationbuilder.py index 2d3f20490..b0f054013 100644 --- a/telegram/ext/_applicationbuilder.py +++ b/telegram/ext/_applicationbuilder.py @@ -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`. If not called, a queue will be instantiated. - .. seealso:: :attr:`telegram.ext.Updater.update_queue` + .. seealso:: :attr:`telegram.ext.Updater.update_queue` Args: update_queue (:class:`asyncio.Queue`): The queue. diff --git a/telegram/ext/_basepersistence.py b/telegram/ext/_basepersistence.py index 09c82f7e7..6c2901529 100644 --- a/telegram/ext/_basepersistence.py +++ b/telegram/ext/_basepersistence.py @@ -26,7 +26,8 @@ from telegram.ext._utils.types import BD, CD, UD, CDCData, ConversationDict, Con 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: 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 :class:`~telegram.ext.Application` will update 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 @@ -186,9 +188,9 @@ class BasePersistence(Generic[UD, CD, BD], ABC): :obj:`dict`. In the latter case, the dictionary should produce values corresponding to one of the following: - * :obj:`dict` - * The type from :attr:`telegram.ext.ContextTypes.user_data` - if :class:`telegram.ext.ContextTypes` is used. + - :obj:`dict` + - The type from :attr:`telegram.ext.ContextTypes.user_data` + if :class:`telegram.ext.ContextTypes` is used. .. versionchanged:: 20.0 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 corresponding to one of the following: - * :obj:`dict` - * The type from :attr:`telegram.ext.ContextTypes.chat_data` - if :class:`telegram.ext.ContextTypes` is used. + - :obj:`dict` + - The type from :attr:`telegram.ext.ContextTypes.chat_data` + if :class:`telegram.ext.ContextTypes` is used. .. versionchanged:: 20.0 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 corresponding to one of the following: - * :obj:`dict` - * The type from :attr:`telegram.ext.ContextTypes.bot_data` - if :class:`telegram.ext.ContextTypes` are used. + - :obj:`dict` + - The type from :attr:`telegram.ext.ContextTypes.bot_data` + if :class:`telegram.ext.ContextTypes` are used. Returns: 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`. Returns: - Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ - Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]]: - The restored metadata or :obj:`None`, if no data was stored. + Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]], + Dict[:obj:`str`, :obj:`str`]] | :obj:`None`: The restored metadata or :obj:`None`, + if no data was stored. """ @abstractmethod @@ -320,8 +322,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC): Changed this method into an :external:func:`~abc.abstractmethod`. Args: - data (Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ - Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]]]): + data (Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ + Dict[:obj:`str`, :obj:`Any`]]], Dict[:obj:`str`, :obj:`str`]] | :obj:`None`): The relevant data to restore :class:`telegram.ext.CallbackDataCache`. """ diff --git a/telegram/ext/_callbackqueryhandler.py b/telegram/ext/_callbackqueryhandler.py index a986cbd7a..4f4cf1210 100644 --- a/telegram/ext/_callbackqueryhandler.py +++ b/telegram/ext/_callbackqueryhandler.py @@ -72,11 +72,11 @@ class CallbackQueryHandler(BaseHandler[Update, CCT]): objects as :paramref:`~telegram.InlineKeyboardButton.callback_data`, non-strings will be accepted. To filter arbitrary objects you may pass: - * a callable, accepting exactly one argument, namely the - :attr:`telegram.CallbackQuery.data`. It must return :obj:`True` or - :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 - (or a subclass), the update will be handled. + - a callable, accepting exactly one argument, namely the + :attr:`telegram.CallbackQuery.data`. It must return :obj:`True` or + :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 + (or a subclass), the update will be handled. If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the :class:`telegram.CallbackQuery` update will not be handled. diff --git a/telegram/ext/_commandhandler.py b/telegram/ext/_commandhandler.py index 7ad6b3105..1c8d656b9 100644 --- a/telegram/ext/_commandhandler.py +++ b/telegram/ext/_commandhandler.py @@ -46,7 +46,12 @@ class CommandHandler(BaseHandler[Update, CCT]): in the filter argument. 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: When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom diff --git a/telegram/ext/_defaults.py b/telegram/ext/_defaults.py index f34fdec41..0636322da 100644 --- a/telegram/ext/_defaults.py +++ b/telegram/ext/_defaults.py @@ -41,7 +41,7 @@ class Defaults: 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. 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. 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 @@ -173,7 +173,7 @@ class Defaults: @property def quote(self) -> Optional[bool]: """: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. """ return self._quote diff --git a/telegram/ext/_dictpersistence.py b/telegram/ext/_dictpersistence.py index eaf7999a4..5460155c4 100644 --- a/telegram/ext/_dictpersistence.py +++ b/telegram/ext/_dictpersistence.py @@ -58,7 +58,7 @@ class DictPersistence(BasePersistence): bot_data on creating this persistence. Default is ``""``. conversations_json (:obj:`str`, optional): JSON string that will be used to reconstruct 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 ``""``. .. versionadded:: 13.6 diff --git a/telegram/ext/_jobqueue.py b/telegram/ext/_jobqueue.py index f34c79090..c852a9305 100644 --- a/telegram/ext/_jobqueue.py +++ b/telegram/ext/_jobqueue.py @@ -44,7 +44,7 @@ class JobQueue: scheduler (:class:`apscheduler.schedulers.asyncio.AsyncIOScheduler`): The scheduler. .. versionchanged:: 20.0 - Use :class:`~apscheduler.schedulers.asyncio.AsyncIOScheduler` instead of + Uses :class:`~apscheduler.schedulers.asyncio.AsyncIOScheduler` instead of :class:`~apscheduler.schedulers.background.BackgroundScheduler` @@ -248,13 +248,13 @@ class JobQueue: tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the default timezone of the bot will be used. - Defaults to ``interval`` + Defaults to :paramref:`interval` last (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | \ :obj:`datetime.datetime` | :obj:`datetime.time`, optional): 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 assumed. @@ -329,8 +329,8 @@ class JobQueue: """Creates a new :class:`Job` that runs on a monthly basis and adds it to the queue. .. versionchanged:: 20.0 - The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day`` - parameter to have the job run on the last day of the month. + The ``day_is_strict`` argument was removed. Instead one can now pass ``-1`` to the + :paramref:`day` parameter to have the job run on the last day of the month. Args: 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.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 - be within the range of 1 and 31, inclusive. If a month has fewer days than this - number, the job will not run in this month. Passing -1 leads to the job running on - the last day of the month. + be within the range of ``1`` and ``31``, inclusive. If a month has fewer days than + this number, the job will not run in this month. Passing ``-1`` leads to the job + running on the last day of the month. data (:obj:`object`, optional): Additional data needed for the callback function. Can be accessed through :attr:`Job.data` in the callback. Defaults to :obj:`None`. @@ -535,7 +535,7 @@ class JobQueue: async def start(self) -> None: # 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: self.scheduler.start() diff --git a/telegram/ext/_picklepersistence.py b/telegram/ext/_picklepersistence.py index 77bd51f42..e08bce5d8 100644 --- a/telegram/ext/_picklepersistence.py +++ b/telegram/ext/_picklepersistence.py @@ -343,9 +343,9 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): .. versionadded:: 13.6 Returns: - Optional[Tuple[List[Tuple[:obj:`str`, :obj:`float`, \ - Dict[:obj:`str`, :class:`object`]]], Dict[:obj:`str`, :obj:`str`]]]: - The restored metadata or :obj:`None`, if no data was stored. + Tuple[List[Tuple[:obj:`str`, :obj:`float`, Dict[:obj:`str`, :class:`object`]]], + Dict[:obj:`str`, :obj:`str`]] | :obj:`None`: The restored metadata or :obj:`None`, + if no data was stored. """ if self.callback_data: pass diff --git a/telegram/ext/_updater.py b/telegram/ext/_updater.py index 536b4f443..de50dfa7b 100644 --- a/telegram/ext/_updater.py +++ b/telegram/ext/_updater.py @@ -373,9 +373,9 @@ class Updater(AbstractAsyncContextManager): """ Starts a small http server to listen for updates via webhook. If :paramref:`cert` and :paramref:`key` are not provided, the webhook will be started directly on - http://listen:port/url_path, so SSL can be handled by another + ``http://listen:port/url_path``, so SSL can be handled by another application. Else, the webhook will be started on - https://listen:port/url_path. Also calls :meth:`telegram.Bot.set_webhook` as required. + ``https://listen:port/url_path``. Also calls :meth:`telegram.Bot.set_webhook` as required. .. versionchanged:: 13.4 :meth:`start_webhook` now *always* calls :meth:`telegram.Bot.set_webhook`, so pass