Upload 184 files

.git-blame-ignore-revs

@@ -0,0 +1,7 @@
+# .git-blame-ignore-revs
+# Use locally as `git blame file.py --ignore-revs-file .git-blame-ignore-revs`
+# or configure git to always use it: `git config blame.ignoreRevsFile .git-blame-ignore-revs`
+# First migration to code style Black (#2122)
+264b2c9c72691c5937b80e84e061c52dd2d8861a
+# Use Black more extensively (#2972)
+950d9a0751d79b92d78ea44344ce3e3c5b3948f9

.gitignore

@@ -0,0 +1,97 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+.pybuild
+debian/tmp
+debian/python3-telegram
+debian/python3-telegram-doc
+debian/.debhelper
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache
+.mypy_cache
+nosetests.xml
+coverage.xml
+*,cover
+.coveralls.yml
+.testmondata
+.testmondata-journal
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+.idea/
+
+# Sublime Text 2
+*.sublime*
+
+# VS Code
+.vscode
+
+# unitests files
+game.gif
+telegram.mp3
+telegram.mp4
+telegram2.mp4
+telegram.ogg
+telegram.png
+telegram.webp
+telegram.jpg
+
+# original files from merges
+*.orig
+
+# Exclude .exrc file for Vim
+.exrc
+
+# virtual env
+venv*
+
+# environment manager:
+.mise.toml

.pre-commit-config.yaml

@@ -0,0 +1,83 @@
+# Make sure that the additional_dependencies here match pyproject.toml
+
+ci:
+    autofix_prs: false
+    autoupdate_schedule: quarterly
+    autoupdate_commit_msg: 'Bump `pre-commit` Hooks to Latest Versions'
+
+repos:
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.5.6'
+    hooks:
+    -   id: ruff
+        name: ruff
+        additional_dependencies:
+          - httpx~=0.27
+          - tornado~=6.4
+          - APScheduler~=3.10.4
+          - cachetools>=5.3.3,<5.5.0
+          - aiolimiter~=1.1.0
+-   repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.4.2
+    hooks:
+    -   id: black
+        args:
+        - --diff
+        - --check
+-   repo: https://github.com/PyCQA/flake8
+    rev: 7.1.0
+    hooks:
+    -   id: flake8
+-   repo: https://github.com/PyCQA/pylint
+    rev: v3.2.4
+    hooks:
+    -   id: pylint
+        files: ^(?!(tests|docs)).*\.py$
+        additional_dependencies:
+          - httpx~=0.27
+          - tornado~=6.4
+          - APScheduler~=3.10.4
+          - cachetools>=5.3.3,<5.5.0
+          - aiolimiter~=1.1.0
+          - . # this basically does `pip install -e .`
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.1
+    hooks:
+    -   id: mypy
+        name: mypy-ptb
+        files: ^(?!(tests|examples|docs)).*\.py$
+        additional_dependencies:
+          - types-pytz
+          - types-cryptography
+          - types-cachetools
+          - httpx~=0.27
+          - tornado~=6.4
+          - APScheduler~=3.10.4
+          - cachetools>=5.3.3,<5.5.0
+          - aiolimiter~=1.1.0
+          - . # this basically does `pip install -e .`
+    - id: mypy
+      name: mypy-examples
+      files: ^examples/.*\.py$
+      args:
+        - --no-strict-optional
+        - --follow-imports=silent
+      additional_dependencies:
+        - tornado~=6.4
+        - APScheduler~=3.10.4
+        - cachetools>=5.3.3,<5.5.0
+        - . # this basically does `pip install -e .`
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v3.16.0
+    hooks:
+    -   id: pyupgrade
+        args:
+          - --py38-plus
+-   repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+    -   id: isort
+        name: isort
+        args:
+        - --diff
+        - --check

.readthedocs.yml

@@ -0,0 +1,62 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements-docs.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"  # latest stable cpython version
+  jobs:
+    post_build:
+      # Based on https://github.com/readthedocs/readthedocs.org/issues/3242#issuecomment-1410321534
+      # This provides a HTML zip file for download, with the same structure as the hosted website
+      - mkdir --parents $READTHEDOCS_OUTPUT/htmlzip
+      - cp --recursive $READTHEDOCS_OUTPUT/html $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT
+      # Hide the "other versions" dropdown. This is a workaround for those versions being shown,
+      # but not being accessible, as they are not built. Also, they hide the actual sidebar menu
+      # that is relevant only on ReadTheDocs.
+      - echo "#furo-readthedocs-versions{display:none}" >> $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT/_static/styles/furo-extensions.css
+      - cd $READTHEDOCS_OUTPUT ; zip --recurse-path --symlinks htmlzip/$READTHEDOCS_PROJECT.zip $READTHEDOCS_PROJECT
+
+search:
+  ranking: # bump up rank of commonly searched pages: (default: 0, values range from -10 to 10)
+    telegram.bot.html: 7
+    telegram.message.html: 3
+    telegram.update.html: 3
+    telegram.user.html: 2
+    telegram.chat.html: 2
+    telegram.ext.application.html: 3
+    telegram.ext.filters.html: 3
+    telegram.ext.callbackcontext.html: 2
+    telegram.ext.inlinekeyboardbutton.html: 1
+
+    telegram.passport*.html: -7
+
+  ignore:
+    - changelog.html
+    - coc.html
+    - bot_methods.html#
+    - bot_methods.html
+    # Defaults
+    - search.html
+    - search/index.html
+    - 404.html
+    - 404/index.html'

AUTHORS.rst

@@ -0,0 +1,137 @@
+Credits
+=======
+
+``python-telegram-bot`` was originally created by
+`Leandro Toledo <https://github.com/leandrotoledo>`_.
+The current development team includes
+
+- `Hinrich Mahler <https://github.com/Bibo-Joshi>`_ (maintainer)
+- `Poolitzer <https://github.com/Poolitzer>`_ (community liaison)
+- `Shivam <https://github.com/Starry69>`_
+- `Harshil <https://github.com/harshil21>`_
+- `Dmitry Kolomatskiy <https://github.com/lemontree210>`_
+- `Aditya <https://github.com/clot27>`_
+
+Emeritus maintainers include
+`Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram),
+`Noam Meltzer <https://github.com/tsnoam>`_, `Pieter Schutz <https://github.com/eldinnie>`_ and `Jasmin Bom <https://github.com/jsmnbom>`_.
+
+Contributors
+------------
+
+The following wonderful people contributed directly or indirectly to this project:
+
+- `Abdelrahman <https://github.com/aelkheir>`_
+- `Abshar <https://github.com/abxhr>`_
+- `Alateas <https://github.com/alateas>`_
+- `Ales Dokshanin <https://github.com/alesdokshanin>`_
+- `Alexandre <https://github.com/xTudoS>`_
+- `Alizia <https://github.com/thefunkycat>`_
+- `Ambro17 <https://github.com/Ambro17>`_
+- `Andrej Zhilenkov <https://github.com/Andrej730>`_
+- `Anton Tagunov <https://github.com/anton-tagunov>`_
+- `Avanatiker <https://github.com/Avanatiker>`_
+- `Balduro <https://github.com/Balduro>`_
+- `Bibo-Joshi <https://github.com/Bibo-Joshi>`_
+- `Biruk Alamirew <https://github.com/BAcode-X>`_
+- `bimmlerd <https://github.com/bimmlerd>`_
+- `cyc8 <https://github.com/cyc8>`_ 
+- `d-qoi <https://github.com/d-qoi>`_
+- `daimajia <https://github.com/daimajia>`_
+- `Daniel Reed <https://github.com/nmlorg>`_
+- `D David Livingston <https://github.com/daviddl9>`_
+- `DonalDuck004 <https://github.com/DonalDuck004>`_
+- `Eana Hufwe <https://github.com/blueset>`_
+- `Ehsan Online <https://github.com/ehsanonline>`_
+- `Eldad Carin <https://github.com/eldbud>`_
+- `Eli Gao <https://github.com/eligao>`_
+- `Emilio Molinari <https://github.com/xates>`_
+- `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
+- `Eugene Lisitsky <https://github.com/lisitsky>`_
+- `Eugenio Panadero <https://github.com/azogue>`_
+- `Evan Haberecht <https://github.com/habereet>`_
+- `Evgeny Denisov <https://github.com/eIGato>`_
+- `evgfilim1 <https://github.com/evgfilim1>`_
+- `ExalFabu <https://github.com/ExalFabu>`_
+- `franciscod <https://github.com/franciscod>`_
+- `gamgi <https://github.com/gamgi>`_
+- `Gauthamram Ravichandran <https://github.com/GauthamramRavichandran>`_
+- `Harshil <https://github.com/harshil21>`_
+- `Hugo Damer <https://github.com/HakimusGIT>`_
+- `ihoru <https://github.com/ihoru>`_
+- `Iulian Onofrei <https://github.com/revolter>`_
+- `Jainam Oswal <https://github.com/jainamoswal>`_
+- `Jasmin Bom <https://github.com/jsmnbom>`_
+- `JASON0916 <https://github.com/JASON0916>`_
+- `jeffffc <https://github.com/jeffffc>`_
+- `Jelle Besseling <https://github.com/pingiun>`_
+- `jh0ker <https://github.com/jh0ker>`_
+- `jlmadurga <https://github.com/jlmadurga>`_
+- `John Yong <https://github.com/whipermr5>`_
+- `Joscha Götzer <https://github.com/Rostgnom>`_
+- `jossalgon <https://github.com/jossalgon>`_
+- `JRoot3D <https://github.com/JRoot3D>`_
+- `kenjitagawa <https://github.com/kenjitagawa>`_
+- `kennethcheo <https://github.com/kennethcheo>`_
+- `Kirill Vasin <https://github.com/vasinkd>`_
+- `Kjwon15 <https://github.com/kjwon15>`_
+- `Li-aung Yip <https://github.com/LiaungYip>`_
+- `Loo Zheng Yuan <https://github.com/loozhengyuan>`_
+- `LRezende <https://github.com/lrezende>`_
+- `Luca Bellanti <https://github.com/Trifase>`_
+- `Lucas Molinari <https://github.com/lucasmolinari>`_
+- `macrojames <https://github.com/macrojames>`_
+- `Matheus Lemos <https://github.com/mlemosf>`_
+- `Michael Dix <https://github.com/Eisberge>`_
+- `Michael Elovskikh <https://github.com/wronglink>`_
+- `Miguel C. R. <https://github.com/MiguelX413>`_
+- `miles <https://github.com/miles170>`_
+- `Mischa Krüger <https://github.com/Makman2>`_
+- `Mohd Yusuf <https://github.com/mohdyusuf2312>`_
+- `naveenvhegde <https://github.com/naveenvhegde>`_
+- `neurrone <https://github.com/neurrone>`_
+- `NikitaPirate <https://github.com/NikitaPirate>`_
+- `Nikolai Krivenko <https://github.com/nkrivenko>`_
+- `njittam <https://github.com/njittam>`_
+- `Noam Meltzer <https://github.com/tsnoam>`_
+- `Oleg Shlyazhko <https://github.com/ollmer>`_
+- `Oleg Sushchenko <https://github.com/feuillemorte>`_
+- `Or Bin <https://github.com/OrBin>`_
+- `overquota <https://github.com/overquota>`_
+- `Pablo Martinez <https://github.com/elpekenin>`_
+- `Paradox <https://github.com/paradox70>`_
+- `Patrick Hofmann <https://github.com/PH89>`_
+- `Paul Larsen <https://github.com/PaulSonOfLars>`_
+- `Pawan <https://github.com/pawanrai9999>`_
+- `Pieter Schutz <https://github.com/eldinnie>`_
+- `Piraty <https://github.com/piraty>`_
+- `Poolitzer <https://github.com/Poolitzer>`_
+- `Pranjalya Tiwari <https://github.com/Pranjalya>`_
+- `Rahiel Kasim <https://github.com/rahiel>`_
+- `Riko Naka <https://github.com/rikonaka>`_
+- `Rizlas <https://github.com/rizlas>`_
+- `Sahil Sharma <https://github.com/sahilsharma811>`_
+- `Sam Mosleh <https://github.com/sam-mosleh>`_
+- `Sascha <https://github.com/saschalalala>`_
+- `Shelomentsev D <https://github.com/shelomentsevd>`_
+- `Shivam Saini <https://github.com/shivamsn97>`_
+- `Simon Schürrle <https://github.com/SitiSchu>`_
+- `sooyhwang <https://github.com/sooyhwang>`_
+- `syntx <https://github.com/syntx>`_
+- `thodnev <https://github.com/thodnev>`_
+- `Timur Kushukov <https://github.com/timqsh>`_
+- `Trainer Jono <https://github.com/Tr-Jono>`_
+- `Valentijn <https://github.com/Faalentijn>`_
+- `voider1 <https://github.com/voider1>`_
+- `Vorobjev Simon <https://github.com/simonvorobjev>`_
+- `Wagner Macedo <https://github.com/wagnerluis1982>`_
+- `wjt <https://github.com/wjt>`_
+- `Wonseok Oh <https://github.com/marinelay>`_
+- `Yaw Danso <https://github.com/dglitxh>`_
+- `Yao Kuan <https://github.com/thatguylah>`_
+- `zeroone2numeral2 <https://github.com/zeroone2numeral2>`_
+- `zeshuaro <https://github.com/zeshuaro>`_
+- `zpavloudis <https://github.com/zpavloudis>`_
+
+
+Please add yourself here alphabetically when you submit your first pull request.

CHANGES.rst

@@ -0,0 +1,2630 @@
+.. _ptb-changelog:
+
+=========
+Changelog
+=========
+
+Version 21.5
+============
+
+*Released 2024-09-01*
+
+This is the technical changelog for version 21.5. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.9 (:pr:`4429`)
+- Full Support for Bot API 7.8 (:pr:`4408`)
+
+New Features
+------------
+
+- Add ``MessageEntity.shift_entities`` and ``MessageEntity.concatenate`` (:pr:`4376` closes :issue:`4372`)
+- Add Parameter ``game_pattern`` to ``CallbackQueryHandler`` (:pr:`4353` by `jainamoswal <https://github.com/jainamoswal>`_ closes :issue:`4269`)
+- Add Parameter ``read_file_handle`` to ``InputFile`` (:pr:`4388` closes :issue:`4339`)
+
+Documentation Improvements
+--------------------------
+
+- Bugfix for "Available In" Admonitions (:pr:`4413`)
+- Documentation Improvements (:pr:`4400` closes :issue:`4446`, :pr:`4448` by `Palaptin <https://github.com/Palaptin>`_)
+- Document Return Types of ``RequestData`` Members (:pr:`4396`)
+- Add Introductory Paragraphs to Telegram Types Subsections (:pr:`4389` by `mohdyusuf2312 <https://github.com/mohdyusuf2312>`_ closes :issue:`4380`)
+- Start Adapting to RTD Addons (:pr:`4386`)
+
+Minor and Internal Changes
+---------------------------
+
+- Remove Surplus Logging from ``Updater`` Network Loop (:pr:`4432` by `MartinHjelmare <https://github.com/MartinHjelmare>`_)
+- Add Internal Constants for Encodings (:pr:`4378` by `elpekenin <https://github.com/elpekenin>`_)
+- Improve PyPI Automation (:pr:`4375` closes :issue:`4373`)
+- Update Test Suite to New Test Channel Setup (:pr:`4435`)
+- Improve Fixture Usage in ``test_message.py`` (:pr:`4431` by `Palaptin <https://github.com/Palaptin>`_)
+- Update Python 3.13 Test Suite to RC1 (:pr:`4415`)
+- Bump ``ruff`` and Add New Rules (:pr:`4416`)
+
+Dependency Updates
+------------------
+
+- Update ``cachetools`` requirement from <5.5.0,>=5.3.3 to >=5.3.3,<5.6.0 (:pr:`4437`)
+- Bump ``sphinx`` from 7.4.7 to 8.0.2 and ``furo`` from 2024.7.18 to 2024.8.6 (:pr:`4412`)
+- Bump ``test-summary/action`` from 2.3 to 2.4 (:pr:`4410`)
+- Bump ``pytest`` from 8.2.2 to 8.3.2 (:pr:`4403`)
+- Bump ``dependabot/fetch-metadata`` from 2.1.0 to 2.2.0 (:pr:`4411`)
+- Update ``cachetools`` requirement from ~=5.3.3 to >=5.3.3,<5.5.0 (:pr:`4390`)
+- Bump ``sphinx`` from 7.3.7 to 7.4.7 (:pr:`4395`)
+- Bump ``furo`` from 2024.5.6 to 2024.7.18 (:pr:`4392`)
+
+Version 21.4
+============
+
+*Released 2024-07-12*
+
+This is the technical changelog for version 21.4. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.5 (:pr:`4328`, :pr:`4316`, :pr:`4315`, :pr:`4312` closes :issue:`4310`, :pr:`4311`)
+- Full Support for Bot API 7.6 (:pr:`4333` closes :issue:`4331`, :pr:`4344`, :pr:`4341`, :pr:`4334`, :pr:`4335`, :pr:`4351`, :pr:`4342`, :pr:`4348`)
+- Full Support for Bot API 7.7 (:pr:`4356` closes :issue:`4355`)
+- Drop ``python-telegram-bot-raw`` And Switch to ``pyproject.toml`` Based Packaging (:pr:`4288` closes :issue:`4129` and :issue:`4296`)
+- Deprecate Inclusion of ``successful_payment`` in ``Message.effective_attachment`` (:pr:`4365` closes :issue:`4350`)
+
+New Features
+------------
+
+- Add Support for Python 3.13 Beta (:pr:`4253`)
+- Add ``filters.PAID_MEDIA`` (:pr:`4357`)
+- Log Received Data on Deserialization Errors (:pr:`4304`)
+- Add ``MessageEntity.adjust_message_entities_to_utf_16`` Utility Function (:pr:`4323` by `Antares0982 <https://github.com/Antares0982>`_ closes :issue:`4319`)
+- Make Argument ``bot`` of ``TelegramObject.de_json`` Optional (:pr:`4320`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4303` closes :issue:`4301`)
+- Restructure Readme (:pr:`4362`)
+- Fix Link-Check Workflow (:pr:`4332`)
+
+Internal Changes
+----------------
+
+- Automate PyPI Releases (:pr:`4364` closes :issue:`4318`)
+- Add ``mise-en-place`` to ``.gitignore`` (:pr:`4300`)
+- Use a Composite Action for Testing Type Completeness (:pr:`4367`)
+- Stabilize Some Concurrency Usages in Test Suite (:pr:`4360`)
+- Add a Test Case for ``MenuButton`` (:pr:`4363`)
+- Extend ``SuccessfulPayment`` Test (:pr:`4349`)
+- Small Fixes for ``test_stars.py`` (:pr:`4347`)
+- Use Python 3.13 Beta 3 in Test Suite (:pr:`4336`)
+
+Dependency Updates
+------------------
+
+- Bump ``ruff`` and Add New Rules (:pr:`4329`)
+- Bump ``pre-commit`` Hooks to Latest Versions (:pr:`4337`)
+- Add Lower Bound for ``flaky`` Dependency (:pr:`4322` by `Palaptin <https://github.com/Palaptin>`_)
+- Bump ``pytest`` from 8.2.1 to 8.2.2 (:pr:`4294`)
+
+Version 21.3
+============
+*Released 2024-06-07*
+
+This is the technical changelog for version 21.3. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.4 (:pr:`4286`, :pr:`4276` closes :issue:`4275`, :pr:`4285`, :pr:`4283`, :pr:`4280`, :pr:`4278`, :pr:`4279`)
+- Deprecate ``python-telegram-bot-raw`` (:pr:`4270`)
+- Remove Functionality Deprecated in Bot API 7.3 (:pr:`4266` closes :issue:`4244`)
+
+New Features
+------------
+
+- Add Parameter ``chat_id`` to ``ChatMemberHandler`` (:pr:`4290` by `uniquetrij <https://github.com/uniquetrij>`_ closes :issue:`4287`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4264` closes :issue:`4240`)
+
+Internal Changes
+----------------
+
+- Add ``setuptools`` to ``requirements-dev.txt`` (:pr:`4282`)
+- Update Settings for pre-commit.ci (:pr:`4265`)
+
+Dependency Updates
+------------------
+
+- Bump ``pytest`` from 8.2.0 to 8.2.1 (:pr:`4272`)
+
+Version 21.2
+============
+
+*Released 2024-05-20*
+
+This is the technical changelog for version 21.2. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 7.3 (:pr:`4246`, :pr:`4260`, :pr:`4243`, :pr:`4248`, :pr:`4242` closes :issue:`4236`, :pr:`4247` by `aelkheir <https://github.com/aelkheir>`_)
+- Remove Functionality Deprecated by Bot API 7.2 (:pr:`4245`)
+
+New Features
+------------
+
+- Add Version to ``PTBDeprecationWarning`` (:pr:`4262` closes :issue:`4261`)
+- Handle Exceptions in building ``CallbackContext`` (:pr:`4222`)
+
+Bug Fixes
+---------
+
+- Call ``Application.post_stop`` Only if ``Application.stop`` was called (:pr:`4211` closes :issue:`4210`)
+- Handle ``SystemExit`` raised in Handlers (:pr:`4157` closes :issue:`4155` and :issue:`4156`)
+- Make ``Birthdate.to_date`` Return a ``datetime.date`` Object (:pr:`4251`)
+
+Documentation Improvements
+--------------------------
+
+- Documentation Improvements (:pr:`4217`)
+
+Internal Changes
+----------------
+
+- Add New Rules to ``ruff`` Config (:pr:`4250`)
+- Adapt Test Suite to Changes in Error Messages (:pr:`4238`)
+
+Dependency Updates
+------------------
+
+- Bump ``furo`` from 2024.4.27 to 2024.5.6 (:pr:`4252`)
+- ``pre-commit`` autoupdate (:pr:`4239`)
+- Bump ``pytest`` from 8.1.1 to 8.2.0 (:pr:`4231`)
+- Bump ``dependabot/fetch-metadata`` from 2.0.0 to 2.1.0 (:pr:`4228`)
+- Bump ``pytest-asyncio`` from 0.21.1 to 0.21.2 (:pr:`4232`)
+- Bump ``pytest-xdist`` from 3.6.0 to 3.6.1 (:pr:`4233`)
+- Bump ``furo`` from 2024.1.29 to 2024.4.27 (:pr:`4230`)
+- Bump ``srvaroa/labeler`` from 1.10.0 to 1.10.1 (:pr:`4227`)
+- Bump ``pytest`` from 7.4.4 to 8.1.1 (:pr:`4218`)
+- Bump ``sphinx`` from 7.2.6 to 7.3.7 (:pr:`4215`)
+- Bump ``pytest-xdist`` from 3.5.0 to 3.6.0 (:pr:`4215`)
+
+Version 21.1.1
+==============
+
+*Released 2024-04-15*
+
+This is the technical changelog for version 21.1.1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Bug Fixes
+---------
+
+-  Fix Bug With Parameter ``message_thread_id`` of ``Message.reply_*`` (:pr:`4207` closes :issue:`4205`)
+
+Minor Changes
+-------------
+
+-  Remove Deprecation Warning in ``JobQueue.run_daily`` (:pr:`4206` by `@Konano <https://github.com/Konano>`__)
+-  Fix Annotation of ``EncryptedCredentials.decrypted_secret`` (:pr:`4199` by `@marinelay <https://github.com/marinelay>`__ closes :issue:`4198`)
+
+
+Version 21.1
+==============
+
+*Released 2024-04-12*
+
+This is the technical changelog for version 21.1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Major Changes
+-------------
+
+-  API 7.2 (:pr:`4180` closes :issue:`4179` and :issue:`4181`, :issue:`4181`)
+-  Make ``ChatAdministratorRights/ChatMemberAdministrator.can_*_stories`` Required (API 7.1) (:pr:`4192`)
+
+Minor Changes
+-------------
+
+-  Refactor Debug logging in ``Bot`` to Improve Type Hinting (:pr:`4151` closes :issue:`4010`)
+
+New Features
+------------
+
+-  Make ``Message.reply_*`` Reply in the Same Topic by Default (:pr:`4170` by `@aelkheir <https://github.com/aelkheir>`__ closes :issue:`4139`)
+-  Accept Socket Objects for Webhooks (:pr:`4161` closes :issue:`4078`)
+-  Add ``Update.effective_sender`` (:pr:`4168` by `@aelkheir <https://github.com/aelkheir>`__ closes :issue:`4085`)
+
+Documentation Improvements
+--------------------------
+
+-  Documentation Improvements (:pr:`4171`, :pr:`4158` by `@teslaedison <https://github.com/teslaedison>`__)
+
+Internal Changes
+----------------
+
+-  Temporarily Mark Tests with ``get_sticker_set`` as XFAIL due to API 7.2 Update (:pr:`4190`)
+
+Dependency Updates
+------------------
+
+-  ``pre-commit`` autoupdate (:pr:`4184`)
+-  Bump ``dependabot/fetch-metadata`` from 1.6.0 to 2.0.0 (:pr:`4185`)
+
+
+Version 21.0.1
+==============
+
+*Released 2024-03-06*
+
+This is the technical changelog for version 21.0.1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Bug Fixes
+---------
+
+-  Remove ``docs`` from Package (:pr:`4150`)
+
+
+Version 21.0
+============
+
+*Released 2024-03-06*
+
+This is the technical changelog for version 21.0. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Major Changes
+-------------
+
+-  Remove Functionality Deprecated in API 7.0 (:pr:`4114` closes :issue:`4099`)
+-  API 7.1 (:pr:`4118`)
+
+New Features
+------------
+
+-  Add Parameter ``media_write_timeout`` to ``HTTPXRequest`` and Method ``ApplicationBuilder.media_write_timeout`` (:pr:`4120` closes :issue:`3864`)
+-  Handle Properties in ``TelegramObject.__setstate__`` (:pr:`4134` closes :issue:`4111`)
+
+Bug Fixes
+---------
+
+-  Add Missing Slot to ``Updater`` (:pr:`4130` closes :issue:`4127`)
+
+Documentation Improvements
+--------------------------
+
+-  Improve HTML Download of Documentation (:pr:`4146` closes :issue:`4050`)
+-  Documentation Improvements (:pr:`4109`, :issue:`4116`)
+-  Update Copyright to 2024 (:pr:`4121` by `@aelkheir <https://github.com/aelkheir>`__ closes :issue:`4041`)
+
+Internal Changes
+----------------
+
+-  Apply ``pre-commit`` Checks More Widely (:pr:`4135`)
+-  Refactor and Overhaul ``test_official`` (:pr:`4087` closes :issue:`3874`)
+-  Run Unit Tests in PRs on Requirements Changes (:pr:`4144`)
+-  Make ``Updater.stop`` Independent of ``CancelledError`` (:pr:`4126`)
+
+Dependency Updates
+------------------
+
+-  Relax Upper Bound for ``httpx`` Dependency (:pr:`4148`)
+-  Bump ``test-summary/action`` from 2.2 to 2.3 (:pr:`4142`)
+-  Update ``cachetools`` requirement from ~=5.3.2 to ~=5.3.3 (:pr:`4141`)
+-  Update ``httpx`` requirement from ~=0.26.0 to ~=0.27.0 (:pr:`4131`)
+
+
+Version 20.8
+============
+
+*Released 2024-02-08*
+
+This is the technical changelog for version 20.8. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Major Changes
+-------------
+
+-  API 7.0 (:pr:`4034` closes :issue:`4033`, :pr:`4038` by `@aelkheir <https://github.com/aelkheir>`__)
+
+Minor Changes
+-------------
+
+-  Fix Type Hint for ``filters`` Parameter of ``MessageHandler`` (:pr:`4039` by `@Palaptin <https://github.com/Palaptin>`__)
+-  Deprecate ``filters.CHAT`` (:pr:`4083` closes :issue:`4062`)
+-  Improve Error Handling in Built-In Webhook Handler (:pr:`3987` closes :issue:`3979`)
+
+New Features
+------------
+
+-  Add Parameter ``pattern`` to ``PreCheckoutQueryHandler`` and ``filters.SuccessfulPayment`` (:pr:`4005` by `@aelkheir <https://github.com/aelkheir>`__ closes :issue:`3752`)
+-  Add Missing Conversions of ``type`` to Corresponding Enum from ``telegram.constants`` (:pr:`4067`)
+-  Add Support for Unix Sockets to ``Updater.start_webhook`` (:pr:`3986` closes :issue:`3978`)
+-  Add ``Bot.do_api_request`` (:pr:`4084` closes :issue:`4053`)
+-  Add ``AsyncContextManager`` as Parent Class to ``BaseUpdateProcessor`` (:pr:`4001`)
+
+Documentation Improvements
+--------------------------
+
+-  Documentation Improvements (:pr:`3919`)
+-  Add Docstring to Dunder Methods (:pr:`3929` closes :issue:`3926`)
+-  Documentation Improvements (:pr:`4002`, :pr:`4079` by `@kenjitagawa <https://github.com/kenjitagawa>`__, :pr:`4104` by `@xTudoS <https://github.com/xTudoS>`__)
+
+Internal Changes
+----------------
+
+-  Drop Usage of DeepSource (:pr:`4100`)
+-  Improve Type Completeness & Corresponding Workflow (:pr:`4035`)
+-  Bump ``ruff`` and Remove ``sort-all`` (:pr:`4075`)
+-  Move Handler Files to ``_handlers`` Subdirectory (:pr:`4064` by `@lucasmolinari <https://github.com/lucasmolinari>`__ closes :issue:`4060`)
+-  Introduce ``sort-all`` Hook for ``pre-commit`` (:pr:`4052`)
+-  Use Recommended ``pre-commit`` Mirror for ``black`` (:pr:`4051`)
+-  Remove Unused ``DEFAULT_20`` (:pr:`3997`)
+-  Migrate From ``setup.cfg`` to ``pyproject.toml`` Where Possible (:pr:`4088`)
+
+Dependency Updates
+------------------
+
+-  Bump ``black`` and ``ruff`` (:pr:`4089`)
+-  Bump ``srvaroa/labeler`` from 1.8.0 to 1.10.0 (:pr:`4048`)
+-  Update ``tornado`` requirement from ~=6.3.3 to ~=6.4 (:pr:`3992`)
+-  Bump ``actions/stale`` from 8 to 9 (:pr:`4046`)
+-  Bump ``actions/setup-python`` from 4 to 5 (:pr:`4047`)
+-  ``pre-commit`` autoupdate (:pr:`4101`)
+-  Bump ``actions/upload-artifact`` from 3 to 4 (:pr:`4045`)
+-  ``pre-commit`` autoupdate (:pr:`3996`)
+-  Bump ``furo`` from 2023.9.10 to 2024.1.29 (:pr:`4094`)
+-  ``pre-commit`` autoupdate (:pr:`4043`)
+-  Bump ``codecov/codecov-action`` from 3 to 4 (:pr:`4091`)
+-  Bump ``EndBug/add-and-commit`` from 9.1.3 to 9.1.4 (:pr:`4090`)
+-  Update ``httpx`` requirement from ~=0.25.2 to ~=0.26.0 (:pr:`4024`)
+-  Bump ``pytest`` from 7.4.3 to 7.4.4 (:pr:`4056`)
+-  Bump ``srvaroa/labeler`` from 1.7.0 to 1.8.0 (:pr:`3993`)
+-  Bump ``test-summary/action`` from 2.1 to 2.2 (:pr:`4044`)
+-  Bump ``dessant/lock-threads`` from 4.0.1 to 5.0.1 (:pr:`3994`)
+
+
+Version 20.7
+============
+
+*Released 2023-11-27*
+
+This is the technical changelog for version 20.7. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+New Features
+------------
+
+-  Add ``JobQueue.scheduler_configuration`` and Corresponding Warnings (:pr:`3913` closes :issue:`3837`)
+-  Add Parameter ``socket_options`` to ``HTTPXRequest`` (:pr:`3935` closes :issue:`2965`)
+-  Add ``ApplicationBuilder.(get_updates_)socket_options`` (:pr:`3943`)
+-  Improve ``write_timeout`` Handling for Media Methods (:pr:`3952`)
+-  Add ``filters.Mention`` (:pr:`3941` closes :issue:`3799`)
+-  Rename ``proxy_url`` to ``proxy`` and Allow ``httpx.{Proxy, URL}`` as Input (:pr:`3939` closes :issue:`3844`)
+
+Bug Fixes & Changes
+-------------------
+
+-  Adjust ``read_timeout`` Behavior for ``Bot.get_updates`` (:pr:`3963` closes :issue:`3893`)
+-  Improve ``BaseHandler.__repr__`` for Callbacks without ``__qualname__`` (:pr:`3934`)
+-  Fix Persistency Issue with Ended Non-Blocking Conversations (:pr:`3962`)
+-  Improve Type Hinting for Arguments with Default Values in ``Bot`` (:pr:`3942`)
+
+Documentation Improvements
+--------------------------
+
+-  Add Documentation for ``__aenter__`` and ``__aexit__`` Methods (:pr:`3907` closes :issue:`3886`)
+-  Improve Insertion of Kwargs into ``Bot`` Methods (:pr:`3965`)
+
+Internal Changes
+----------------
+
+-  Adjust Tests to New Error Messages (:pr:`3970`)
+
+Dependency Updates
+------------------
+
+-  Bump ``pytest-xdist`` from 3.3.1 to 3.4.0 (:pr:`3975`)
+-  ``pre-commit`` autoupdate (:pr:`3967`)
+-  Update ``httpx`` requirement from ~=0.25.1 to ~=0.25.2 (:pr:`3983`)
+-  Bump ``pytest-xdist`` from 3.4.0 to 3.5.0 (:pr:`3982`)
+-  Update ``httpx`` requirement from ~=0.25.0 to ~=0.25.1 (:pr:`3961`)
+-  Bump ``srvaroa/labeler`` from 1.6.1 to 1.7.0 (:pr:`3958`)
+-  Update ``cachetools`` requirement from ~=5.3.1 to ~=5.3.2 (:pr:`3954`)
+-  Bump ``pytest`` from 7.4.2 to 7.4.3 (:pr:`3953`)
+
+
+Version 20.6
+============
+
+*Released 2023-10-03*
+
+This is the technical changelog for version 20.6. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Major Changes
+-------------
+
+-  Drop Backward Compatibility Layer Introduced in :pr:`3853` (API 6.8) (:pr:`3873`)
+-  Full Support for Bot API 6.9 (:pr:`3898`)
+
+New Features
+------------
+
+-  Add Rich Equality Comparison to ``WriteAccessAllowed`` (:pr:`3911` closes :issue:`3909`)
+-  Add ``__repr__`` Methods Added in :pr:`3826` closes :issue:`3770` to Sphinx Documentation (:pr:`3901` closes :issue:`3889`)
+-  Add String Representation for Selected Classes (:pr:`3826` closes :issue:`3770`)
+
+Minor Changes
+-------------
+
+-  Add Support Python 3.12 (:pr:`3915`)
+-  Documentation Improvements (:pr:`3910`)
+
+Internal Changes
+----------------
+
+-  Verify Type Hints for Bot Method & Telegram Class Parameters (:pr:`3868`)
+-  Move Bot API Tests to Separate Workflow File (:pr:`3912`)
+-  Fix Failing ``file_size`` Tests (:pr:`3906`)
+-  Set Threshold for DeepSource’s PY-R1000 to High (:pr:`3888`)
+-  One-Time Code Formatting Improvement via ``--preview`` Flag of ``black`` (:pr:`3882`)
+-  Move Dunder Methods to the Top of Class Bodies (:pr:`3883`)
+-  Remove Superfluous ``Defaults.__ne__`` (:pr:`3884`)
+
+Dependency Updates
+------------------
+
+-  ``pre-commit`` autoupdate (:pr:`3876`)
+-  Update ``pre-commit`` Dependencies (:pr:`3916`)
+-  Bump ``actions/checkout`` from 3 to 4 (:pr:`3914`)
+-  Update ``httpx`` requirement from ~=0.24.1 to ~=0.25.0 (:pr:`3891`)
+-  Bump ``furo`` from 2023.8.19 to 2023.9.10 (:pr:`3890`)
+-  Bump ``sphinx`` from 7.2.5 to 7.2.6 (:pr:`3892`)
+-  Update ``tornado`` requirement from ~=6.2 to ~=6.3.3 (:pr:`3675`)
+-  Bump ``pytest`` from 7.4.0 to 7.4.2 (:pr:`3881`)
+
+
+Version 20.5
+============
+*Released 2023-09-03*
+
+This is the technical changelog for version 20.5. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Major Changes
+-------------
+
+-  API 6.8 (:pr:`3853`)
+-  Remove Functionality Deprecated Since Bot API 6.5, 6.6 or 6.7 (:pr:`3858`)
+
+New Features
+------------
+
+-  Extend Allowed Values for HTTP Version (:pr:`3823` closes :issue:`3821`)
+-  Add ``has_args`` Parameter to ``CommandHandler`` (:pr:`3854` by `@thatguylah <https://github.com/thatguylah>`__ closes :issue:`3798`)
+-  Add ``Application.stop_running()`` and Improve Marking Updates as Read on ``Updater.stop()`` (:pr:`3804`)
+
+Minor Changes
+-------------
+
+-  Type Hinting Fixes for ``WebhookInfo`` (:pr:`3871`)
+-  Test and Document ``Exception.__cause__`` on ``NetworkError`` (:pr:`3792` closes :issue:`3778`)
+-  Add Support for Python 3.12 RC (:pr:`3847`)
+
+Documentation Improvements
+--------------------------
+
+-  Remove Version Check from Examples (:pr:`3846`)
+-  Documentation Improvements (:pr:`3803`, :pr:`3797`, :pr:`3816` by `@trim21 <https://github.com/trim21>`__, :pr:`3829` by `@aelkheir <https://github.com/aelkheir>`__)
+-  Provide Versions of ``customwebhookbot.py`` with Different Frameworks (:pr:`3820` closes :issue:`3717`)
+
+Dependency Updates
+------------------
+
+-  ``pre-commit`` autoupdate (:pr:`3824`)
+-  Bump ``srvaroa/labeler`` from 1.6.0 to 1.6.1 (:pr:`3870`)
+-  Bump ``sphinx`` from 7.0.1 to 7.1.1 (:pr:`3818`)
+-  Bump ``sphinx`` from 7.2.3 to 7.2.5 (:pr:`3869`)
+-  Bump ``furo`` from 2023.5.20 to 2023.7.26 (:pr:`3817`)
+-  Update ``apscheduler`` requirement from ~=3.10.3 to ~=3.10.4 (:pr:`3862`)
+-  Bump ``sphinx`` from 7.2.2 to 7.2.3 (:pr:`3861`)
+-  Bump ``pytest-asyncio`` from 0.21.0 to 0.21.1 (:pr:`3801`)
+-  Bump ``sphinx-paramlinks`` from 0.5.4 to 0.6.0 (:pr:`3840`)
+-  Update ``apscheduler`` requirement from ~=3.10.1 to ~=3.10.3 (:pr:`3851`)
+-  Bump ``furo`` from 2023.7.26 to 2023.8.19 (:pr:`3850`)
+-  Bump ``sphinx`` from 7.1.2 to 7.2.2 (:pr:`3852`)
+-  Bump ``sphinx`` from 7.1.1 to 7.1.2 (:pr:`3827`)
+
+
+Version 20.4
+============
+
+*Released 2023-07-09*
+
+This is the technical changelog for version 20.4. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`__.
+
+Major Changes
+-------------
+
+-  Drop Support for Python 3.7 (:pr:`3728`, :pr:`3742` by `@Trifase <https://github.com/Trifase>`__, :pr:`3749` by `@thefunkycat <https://github.com/thefunkycat>`__, :pr:`3740` closes :issue:`3732`, :pr:`3754` closes :issue:`3731`, :pr:`3753`, :pr:`3764`, :pr:`3762`, :pr:`3759` closes :issue:`3733`)
+
+New Features
+------------
+
+-  Make Integration of ``APScheduler`` into ``JobQueue`` More Explicit (:pr:`3695`)
+-  Introduce ``BaseUpdateProcessor`` for Customized Concurrent Handling of Updates (:pr:`3654` closes :issue:`3509`)
+
+Minor Changes
+-------------
+
+-  Fix Inconsistent Type Hints for ``timeout`` Parameter of ``Bot.get_updates`` (:pr:`3709` by `@revolter <https://github.com/revolter>`__)
+-  Use Explicit Optionals (:pr:`3692` by `@MiguelX413 <https://github.com/MiguelX413>`__)
+
+Bug Fixes
+---------
+
+-  Fix Wrong Warning Text in ``KeyboardButton.__eq__`` (:pr:`3768`)
+
+Documentation Improvements
+--------------------------
+
+-  Explicitly set ``allowed_updates`` in Examples (:pr:`3741` by `@Trifase <https://github.com/Trifase>`__ closes :issue:`3726`)
+-  Bump ``furo`` and ``sphinx`` (:pr:`3719`)
+-  Documentation Improvements (:pr:`3698`, :pr:`3708` by `@revolter <https://github.com/revolter>`__, :pr:`3767`)
+-  Add Quotes for Installation Instructions With Optional Dependencies (:pr:`3780`)
+-  Exclude Type Hints from Stability Policy (:pr:`3712`)
+-  Set ``httpx`` Logging Level to Warning in Examples (:pr:`3746` closes :issue:`3743`)
+
+Internal Changes
+----------------
+
+-  Drop a Legacy ``pre-commit.ci`` Configuration (:pr:`3697`)
+-  Add Python 3.12 Beta to the Test Matrix (:pr:`3751`)
+-  Use Temporary Files for Testing File Downloads (:pr:`3777`)
+-  Auto-Update Changed Version in Other Files After Dependabot PRs (:pr:`3716`)
+-  Add More ``ruff`` Rules (:pr:`3763`)
+-  Rename ``_handler.py`` to ``_basehandler.py`` (:pr:`3761`)
+-  Automatically Label ``pre-commit-ci`` PRs (:pr:`3713`)
+-  Rework ``pytest`` Integration into GitHub Actions (:pr:`3776`)
+-  Fix Two Bugs in GitHub Actions Workflows (:pr:`3739`)
+
+Dependency Updates
+------------------
+
+-  Update ``cachetools`` requirement from ~=5.3.0 to ~=5.3.1 (:pr:`3738`)
+-  Update ``aiolimiter`` requirement from ~=1.0.0 to ~=1.1.0 (:pr:`3707`)
+-  ``pre-commit`` autoupdate (:pr:`3791`)
+-  Bump ``sphinxcontrib-mermaid`` from 0.8.1 to 0.9.2 (:pr:`3737`)
+-  Bump ``pytest-xdist`` from 3.2.1 to 3.3.0 (:pr:`3705`)
+-  Bump ``srvaroa/labeler`` from 1.5.0 to 1.6.0 (:pr:`3786`)
+-  Bump ``dependabot/fetch-metadata`` from 1.5.1 to 1.6.0 (:pr:`3787`)
+-  Bump ``dessant/lock-threads`` from 4.0.0 to 4.0.1 (:pr:`3785`)
+-  Bump ``pytest`` from 7.3.2 to 7.4.0 (:pr:`3774`)
+-  Update ``httpx`` requirement from ~=0.24.0 to ~=0.24.1 (:pr:`3715`)
+-  Bump ``pytest-xdist`` from 3.3.0 to 3.3.1 (:pr:`3714`)
+-  Bump ``pytest`` from 7.3.1 to 7.3.2 (:pr:`3758`)
+-  ``pre-commit`` autoupdate (:pr:`3747`)
+
+
+Version 20.3
+============
+*Released 2023-05-07*
+
+This is the technical changelog for version 20.3. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full support for API 6.7 (:pr:`3673`)
+- Add a Stability Policy (:pr:`3622`)
+
+New Features
+------------
+
+- Add ``Application.mark_data_for_update_persistence`` (:pr:`3607`)
+- Make ``Message.link`` Point to Thread View Where Possible (:pr:`3640`)
+- Localize Received ``datetime`` Objects According to ``Defaults.tzinfo`` (:pr:`3632`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Empower ``ruff`` (:pr:`3594`)
+- Drop Usage of ``sys.maxunicode`` (:pr:`3630`)
+- Add String Representation for ``RequestParameter`` (:pr:`3634`)
+- Stabilize CI by Rerunning Failed Tests (:pr:`3631`)
+- Give Loggers Better Names (:pr:`3623`)
+- Add Logging for Invalid JSON Data in ``BasePersistence.parse_json_payload`` (:pr:`3668`)
+- Improve Warning Categories & Stacklevels (:pr:`3674`)
+- Stabilize ``test_delete_sticker_set`` (:pr:`3685`)
+- Shield Update Fetcher Task in ``Application.start`` (:pr:`3657`)
+- Recover 100% Type Completeness (:pr:`3676`)
+- Documentation Improvements (:pr:`3628`, :pr:`3636`, :pr:`3694`)
+
+Dependencies
+------------
+
+- Bump ``actions/stale`` from 7 to 8 (:pr:`3644`)
+- Bump ``furo`` from 2023.3.23 to 2023.3.27 (:pr:`3643`)
+- ``pre-commit`` autoupdate (:pr:`3646`, :pr:`3688`)
+- Remove Deprecated ``codecov`` Package from CI (:pr:`3664`)
+- Bump ``sphinx-copybutton`` from 0.5.1 to 0.5.2 (:pr:`3662`)
+- Update ``httpx`` requirement from ~=0.23.3 to ~=0.24.0 (:pr:`3660`)
+- Bump ``pytest`` from 7.2.2 to 7.3.1 (:pr:`3661`)
+
+Version 20.2
+============
+*Released 2023-03-25*
+
+This is the technical changelog for version 20.2. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+- Full Support for API 6.6 (:pr:`3584`)
+- Revert to HTTP/1.1 as Default and make HTTP/2 an Optional Dependency (:pr:`3576`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+- Documentation Improvements (:pr:`3565`, :pr:`3600`)
+- Handle Symbolic Links in ``was_called_by`` (:pr:`3552`)
+- Tidy Up Tests Directory (:pr:`3553`)
+- Enhance ``Application.create_task`` (:pr:`3543`)
+- Make Type Completeness Workflow Usable for ``PRs`` from Forks (:pr:`3551`)
+- Refactor and Overhaul the Test Suite (:pr:`3426`)
+
+Dependencies
+------------
+- Bump ``pytest-asyncio`` from 0.20.3 to 0.21.0 (:pr:`3624`)
+- Bump ``furo`` from 2022.12.7 to 2023.3.23 (:pr:`3625`)
+- Bump ``pytest-xdist`` from 3.2.0 to 3.2.1 (:pr:`3606`)
+- ``pre-commit`` autoupdate (:pr:`3577`)
+- Update ``apscheduler`` requirement from ~=3.10.0 to ~=3.10.1 (:pr:`3572`)
+- Bump ``pytest`` from 7.2.1 to 7.2.2 (:pr:`3573`)
+- Bump ``pytest-xdist`` from 3.1.0 to 3.2.0 (:pr:`3550`)
+- Bump ``sphinxcontrib-mermaid`` from 0.7.1 to 0.8 (:pr:`3549`)
+
+Version 20.1
+============
+*Released 2023-02-09*
+
+This is the technical changelog for version 20.1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for Bot API 6.5 (:pr:`3530`)
+
+New Features
+------------
+
+- Add ``Application(Builder).post_stop`` (:pr:`3466`)
+- Add ``Chat.effective_name`` Convenience Property (:pr:`3485`)
+- Allow to Adjust HTTP Version and Use HTTP/2 by Default (:pr:`3506`)
+
+Documentation Improvements
+--------------------------
+
+- Enhance ``chatmemberbot`` Example (:pr:`3500`)
+- Automatically Generate Cross-Reference Links (:pr:`3501`, :pr:`3529`, :pr:`3523`)
+- Add Some Graphic Elements to Docs (:pr:`3535`)
+- Various Smaller Improvements (:pr:`3464`, :pr:`3483`, :pr:`3484`, :pr:`3497`, :pr:`3512`, :pr:`3515`,  :pr:`3498`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Update Copyright to 2023 (:pr:`3459`)
+- Stabilize Tests on Closing and Hiding the General Forum Topic (:pr:`3460`)
+- Fix Dependency Warning Typo (:pr:`3474`)
+- Cache Dependencies on ``GitHub`` Actions (:pr:`3469`)
+- Store Documentation Builts as ``GitHub`` Actions Artifacts (:pr:`3468`)
+- Add ``ruff`` to ``pre-commit`` Hooks (:pr:`3488`)
+- Improve Warning for ``days`` Parameter of  ``JobQueue.run_daily`` (:pr:`3503`)
+- Improve Error Message for ``NetworkError`` (:pr:`3505`)
+- Lock Inactive Threads Only Once Each Day (:pr:`3510`)
+- Bump ``pytest`` from 7.2.0 to 7.2.1 (:pr:`3513`)
+- Check for 3D Arrays in ``check_keyboard_type`` (:pr:`3514`)
+- Explicit Type Annotations (:pr:`3508`)
+- Increase Verbosity of Type Completeness CI Job (:pr:`3531`)
+- Fix CI on Python 3.11 + Windows (:pr:`3547`)
+
+Dependencies
+------------
+
+- Bump ``actions/stale`` from 6 to 7 (:pr:`3461`)
+- Bump ``dessant/lock-threads`` from 3.0.0 to 4.0.0 (:pr:`3462`)
+- ``pre-commit`` autoupdate (:pr:`3470`)
+- Update ``httpx`` requirement from ~=0.23.1 to ~=0.23.3 (:pr:`3489`)
+- Update ``cachetools`` requirement from ~=5.2.0 to ~=5.2.1 (:pr:`3502`)
+- Improve Config for ``ruff`` and Bump to ``v0.0.222`` (:pr:`3507`)
+- Update ``cachetools`` requirement from ~=5.2.1 to ~=5.3.0 (:pr:`3520`)
+- Bump ``isort`` to 5.12.0 (:pr:`3525`)
+- Update ``apscheduler`` requirement from ~=3.9.1 to ~=3.10.0 (:pr:`3532`)
+- ``pre-commit`` autoupdate (:pr:`3537`)
+- Update ``cryptography`` requirement to >=39.0.1 to address Vulnerability (:pr:`3539`)
+
+Version 20.0
+============
+*Released 2023-01-01*
+
+This is the technical changelog for version 20.0. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support For Bot API 6.4 (:pr:`3449`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Documentation Improvements (:pr:`3428`, :pr:`3423`, :pr:`3429`, :pr:`3441`, :pr:`3404`, :pr:`3443`)
+- Allow ``Sequence`` Input for Bot Methods (:pr:`3412`)
+- Update Link-Check CI and Replace a Dead Link (:pr:`3456`)
+- Freeze Classes Without Arguments (:pr:`3453`)
+- Add New Constants (:pr:`3444`)
+- Override ``Bot.__deepcopy__`` to Raise ``TypeError`` (:pr:`3446`)
+- Add Log Decorator to ``Bot.get_webhook_info`` (:pr:`3442`)
+- Add Documentation On Verifying Releases (:pr:`3436`)
+- Drop Undocumented ``Job.__lt__`` (:pr:`3432`)
+
+Dependencies
+------------
+
+- Downgrade ``sphinx`` to 5.3.0 to Fix Search (:pr:`3457`)
+- Bump ``sphinx`` from 5.3.0 to 6.0.0 (:pr:`3450`)
+
+Version 20.0b0
+==============
+*Released 2022-12-15*
+
+This is the technical changelog for version 20.0b0. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Make ``TelegramObject`` Immutable (:pr:`3249`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Reduce Code Duplication in Testing ``Defaults`` (:pr:`3419`)
+- Add Notes and Warnings About Optional Dependencies (:pr:`3393`)
+- Simplify Internals of ``Bot`` Methods (:pr:`3396`)
+- Reduce Code Duplication in Several ``Bot`` Methods (:pr:`3385`)
+- Documentation Improvements (:pr:`3386`, :pr:`3395`, :pr:`3398`, :pr:`3403`)
+
+Dependencies
+------------
+
+- Bump ``pytest-xdist`` from 3.0.2 to 3.1.0 (:pr:`3415`)
+- Bump ``pytest-asyncio`` from 0.20.2 to 0.20.3 (:pr:`3417`)
+- ``pre-commit`` autoupdate (:pr:`3409`)
+
+Version 20.0a6
+==============
+*Released 2022-11-24*
+
+This is the technical changelog for version 20.0a6. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Bug Fixes
+---------
+
+- Only Persist Arbitrary ``callback_data`` if ``ExtBot.callback_data_cache`` is Present (:pr:`3384`)
+- Improve Backwards Compatibility of ``TelegramObjects`` Pickle Behavior (:pr:`3382`)
+- Fix Naming and Keyword Arguments of ``File.download_*`` Methods (:pr:`3380`)
+- Fix Return Value Annotation of ``Chat.create_forum_topic`` (:pr:`3381`)
+
+Version 20.0a5
+==============
+*Released 2022-11-22*
+
+This is the technical changelog for version 20.0a5. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- API 6.3 (:pr:`3346`, :pr:`3343`, :pr:`3342`, :pr:`3360`)
+- Explicit ``local_mode`` Setting (:pr:`3154`)
+- Make Almost All 3rd Party Dependencies Optional (:pr:`3267`)
+- Split ``File.download`` Into ``File.download_to_drive`` And ``File.download_to_memory`` (:pr:`3223`)
+
+New Features
+------------
+
+- Add Properties for API Settings of ``Bot`` (:pr:`3247`)
+- Add ``chat_id`` and ``username`` Parameters to ``ChatJoinRequestHandler`` (:pr:`3261`)
+- Introduce ``TelegramObject.api_kwargs`` (:pr:`3233`)
+- Add Two Constants Related to Local Bot API Servers (:pr:`3296`)
+- Add ``recursive`` Parameter to ``TelegramObject.to_dict()`` (:pr:`3276`)
+- Overhaul String Representation of ``TelegramObject`` (:pr:`3234`)
+- Add Methods ``Chat.mention_{html, markdown, markdown_v2}`` (:pr:`3308`)
+- Add ``constants.MessageLimit.DEEP_LINK_LENGTH`` (:pr:`3315`)
+- Add Shortcut Parameters ``caption``, ``parse_mode`` and ``caption_entities`` to ``Bot.send_media_group`` (:pr:`3295`)
+- Add Several New Enums To Constants (:pr:`3351`)
+
+Bug Fixes
+---------
+
+- Fix ``CallbackQueryHandler`` Not Handling Non-String Data Correctly With Regex Patterns (:pr:`3252`)
+- Fix Defaults Handling in ``Bot.answer_web_app_query`` (:pr:`3362`)
+
+Documentation Improvements
+--------------------------
+
+- Update PR Template (:pr:`3361`)
+- Document Dunder Methods of ``TelegramObject`` (:pr:`3319`)
+- Add Several References to Wiki pages (:pr:`3306`)
+- Overhaul Search bar (:pr:`3218`)
+- Unify Documentation of Arguments and Attributes of Telegram Classes (:pr:`3217`, :pr:`3292`, :pr:`3303`, :pr:`3312`, :pr:`3314`)
+- Several Smaller Improvements (:pr:`3214`, :pr:`3271`, :pr:`3289`, :pr:`3326`, :pr:`3370`, :pr:`3376`, :pr:`3366`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Improve Warning About Unknown ``ConversationHandler`` States (:pr:`3242`)
+- Switch from Stale Bot to ``GitHub`` Actions (:pr:`3243`)
+- Bump Python 3.11 to RC2 in Test Matrix (:pr:`3246`)
+- Make ``Job.job`` a Property and Make ``Jobs`` Hashable (:pr:`3250`)
+- Skip ``JobQueue`` Tests on Windows Again (:pr:`3280`)
+- Read-Only ``CallbackDataCache`` (:pr:`3266`)
+- Type Hinting Fix for ``Message.effective_attachment`` (:pr:`3294`)
+- Run Unit Tests in Parallel (:pr:`3283`)
+- Update Test Matrix to Use Stable Python 3.11 (:pr:`3313`)
+- Don't Edit Objects In-Place When Inserting ``ext.Defaults`` (:pr:`3311`)
+- Add a Test for ``MessageAttachmentType`` (:pr:`3335`)
+- Add Three New Test Bots (:pr:`3347`)
+- Improve Unit Tests Regarding ``ChatMemberUpdated.difference`` (:pr:`3352`)
+- Flaky Unit Tests: Use ``pytest`` Marker (:pr:`3354`)
+- Fix ``DeepSource`` Issues (:pr:`3357`)
+- Handle Lists and Tuples and Datetimes Directly in ``TelegramObject.to_dict`` (:pr:`3353`)
+- Update Meta Config (:pr:`3365`)
+- Merge ``ChatDescriptionLimit`` Enum Into ``ChatLimit`` (:pr:`3377`)
+
+Dependencies
+------------
+
+- Bump ``pytest`` from 7.1.2 to 7.1.3 (:pr:`3228`)
+- ``pre-commit`` Updates (:pr:`3221`)
+- Bump ``sphinx`` from 5.1.1 to 5.2.3 (:pr:`3269`)
+- Bump ``furo`` from 2022.6.21 to 2022.9.29 (:pr:`3268`)
+- Bump ``actions/stale`` from 5 to 6 (:pr:`3277`)
+- ``pre-commit`` autoupdate (:pr:`3282`)
+- Bump ``sphinx`` from 5.2.3 to 5.3.0 (:pr:`3300`)
+- Bump ``pytest-asyncio`` from 0.19.0 to 0.20.1 (:pr:`3299`)
+- Bump ``pytest`` from 7.1.3 to 7.2.0 (:pr:`3318`)
+- Bump ``pytest-xdist`` from 2.5.0 to 3.0.2 (:pr:`3317`)
+- ``pre-commit`` autoupdate (:pr:`3325`)
+- Bump ``pytest-asyncio`` from 0.20.1 to 0.20.2 (:pr:`3359`)
+- Update ``httpx`` requirement from ~=0.23.0 to ~=0.23.1 (:pr:`3373`)
+
+Version 20.0a4
+==============
+*Released 2022-08-27*
+
+This is the technical changelog for version 20.0a4. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Hot Fixes
+---------
+
+* Fix a Bug in ``setup.py`` Regarding Optional Dependencies (:pr:`3209`)
+
+Version 20.0a3
+==============
+*Released 2022-08-27*
+
+This is the technical changelog for version 20.0a3. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for API 6.2 (:pr:`3195`)
+
+New Features
+------------
+
+- New Rate Limiting Mechanism (:pr:`3148`)
+- Make ``chat/user_data`` Available in Error Handler for Errors in Jobs (:pr:`3152`)
+- Add ``Application.post_shutdown`` (:pr:`3126`)
+
+Bug Fixes
+---------
+
+- Fix ``helpers.mention_markdown`` for Markdown V1 and Improve Related Unit Tests (:pr:`3155`)
+- Add ``api_kwargs`` Parameter to ``Bot.log_out`` and Improve Related Unit Tests (:pr:`3147`)
+- Make ``Bot.delete_my_commands`` a Coroutine Function (:pr:`3136`)
+- Fix ``ConversationHandler.check_update`` not respecting ``per_user`` (:pr:`3128`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Add Python 3.11 to Test Suite & Adapt Enum Behaviour (:pr:`3168`)
+- Drop Manual Token Validation (:pr:`3167`)
+- Simplify Unit Tests for ``Bot.send_chat_action`` (:pr:`3151`)
+- Drop ``pre-commit`` Dependencies from ``requirements-dev.txt`` (:pr:`3120`)
+- Change Default Values for ``concurrent_updates`` and ``connection_pool_size`` (:pr:`3127`)
+- Documentation Improvements (:pr:`3139`, :pr:`3153`, :pr:`3135`)
+- Type Hinting Fixes (:pr:`3202`)
+
+Dependencies
+------------
+
+- Bump ``sphinx`` from 5.0.2 to 5.1.1 (:pr:`3177`)
+- Update ``pre-commit`` Dependencies (:pr:`3085`)
+- Bump ``pytest-asyncio`` from 0.18.3 to 0.19.0 (:pr:`3158`)
+- Update ``tornado`` requirement from ~=6.1 to ~=6.2 (:pr:`3149`)
+- Bump ``black`` from 22.3.0 to 22.6.0 (:pr:`3132`)
+- Bump ``actions/setup-python`` from 3 to 4 (:pr:`3131`)
+
+Version 20.0a2
+==============
+*Released 2022-06-27*
+
+This is the technical changelog for version 20.0a2. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for API 6.1 (:pr:`3112`)
+
+New Features
+------------
+
+- Add Additional Shortcut Methods to ``Chat`` (:pr:`3115`)
+- Mermaid-based Example State Diagrams (:pr:`3090`)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Documentation Improvements (:pr:`3103`, :pr:`3121`, :pr:`3098`)
+- Stabilize CI (:pr:`3119`)
+- Bump ``pyupgrade`` from 2.32.1 to 2.34.0 (:pr:`3096`)
+- Bump ``furo`` from 2022.6.4 to 2022.6.4.1 (:pr:`3095`)
+- Bump ``mypy`` from 0.960 to 0.961 (:pr:`3093`)
+
+Version 20.0a1
+==============
+*Released 2022-06-09*
+
+This is the technical changelog for version 20.0a1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes:
+--------------
+
+- Drop Support for ``ujson`` and instead ``BaseRequest.parse_json_payload`` (:pr:`3037`, :pr:`3072`)
+- Drop ``InputFile.is_image`` (:pr:`3053`)
+- Drop Explicit Type conversions in ``__init__`` s (:pr:`3056`)
+- Handle List-Valued Attributes More Consistently (:pr:`3057`)
+- Split ``{Command, Prefix}Handler`` And Make Attributes Immutable (:pr:`3045`)
+- Align Behavior Of ``JobQueue.run_daily`` With ``cron`` (:pr:`3046`)
+- Make PTB Specific  Keyword-Only Arguments for PTB Specific in Bot methods (:pr:`3035`)
+- Adjust Equality Comparisons to Fit Bot API 6.0 (:pr:`3033`)
+- Add Tuple Based Version Info (:pr:`3030`)
+- Improve Type Annotations for ``CallbackContext`` and Move Default Type Alias to ``ContextTypes.DEFAULT_TYPE`` (:pr:`3017`, :pr:`3023`)
+- Rename ``Job.context`` to ``Job.data`` (:pr:`3028`)
+- Rename ``Handler`` to ``BaseHandler`` (:pr:`3019`)
+
+New Features:
+-------------
+
+- Add ``Application.post_init`` (:pr:`3078`)
+- Add Arguments ``chat/user_id`` to ``CallbackContext`` And Example On Custom Webhook Setups (:pr:`3059`)
+- Add Convenience Property ``Message.id`` (:pr:`3077`)
+- Add Example for ``WebApp`` (:pr:`3052`)
+- Rename ``telegram.bot_api_version`` to ``telegram.__bot_api_version__`` (:pr:`3030`)
+
+Bug Fixes:
+----------
+
+- Fix Non-Blocking Entry Point in ``ConversationHandler`` (:pr:`3068`)
+- Escape Backslashes in ``escape_markdown``  (:pr:`3055`)
+
+Dependencies:
+-------------
+
+- Update ``httpx`` requirement from ~=0.22.0 to ~=0.23.0 (:pr:`3069`)
+- Update ``cachetools`` requirement from ~=5.0.0 to ~=5.2.0 (:pr:`3058`, :pr:`3080`)
+
+Minor Changes, Documentation Improvements and CI:
+-------------------------------------------------
+
+- Move Examples To Documentation (:pr:`3089`)
+- Documentation Improvements and Update Dependencies (:pr:`3010`, :pr:`3007`, :pr:`3012`, :pr:`3067`, :pr:`3081`, :pr:`3082`)
+- Improve Some Unit Tests (:pr:`3026`)
+- Update Code Quality dependencies (:pr:`3070`, :pr:`3032`,:pr:`2998`, :pr:`2999`)
+- Don't Set Signal Handlers On Windows By Default (:pr:`3065`)
+- Split ``{Command, Prefix}Handler`` And Make Attributes Immutable (:pr:`3045`)
+- Apply ``isort`` and Update ``pre-commit.ci`` Configuration (:pr:`3049`)
+- Adjust ``pre-commit`` Settings for ``isort`` (:pr:`3043`)
+- Add Version Check to Examples (:pr:`3036`)
+- Use ``Collection`` Instead of ``List`` and ``Tuple`` (:pr:`3025`)
+- Remove Client-Side Parameter Validation (:pr:`3024`)
+- Don't Pass Default Values of Optional Parameters to Telegram (:pr:`2978`)
+- Stabilize ``Application.run_*`` on Python 3.7 (:pr:`3009`)
+- Ignore Code Style Commits in ``git blame`` (:pr:`3003`)
+- Adjust Tests to Changed API Behavior (:pr:`3002`)
+
+Version 20.0a0
+==============
+*Released 2022-05-06*
+
+This is the technical changelog for version 20.0a0. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes:
+--------------
+
+-  Refactor Initialization of Persistence Classes
+   (:pr:`2604`)
+-  Drop Non-``CallbackContext`` API
+   (:pr:`2617`)
+-  Remove ``__dict__`` from ``__slots__`` and drop Python 3.6
+   (:pr:`2619`,
+   :pr:`2636`)
+-  Move and Rename ``TelegramDecryptionError`` to
+   ``telegram.error.PassportDecryptionError``
+   (:pr:`2621`)
+-  Make ``BasePersistence`` Methods Abstract
+   (:pr:`2624`)
+-  Remove ``day_is_strict`` argument of ``JobQueue.run_monthly``
+   (:pr:`2634`
+   by `iota-008 <https://github.com/iota-008>`__)
+-  Move ``Defaults`` to ``telegram.ext``
+   (:pr:`2648`)
+-  Remove Deprecated Functionality
+   (:pr:`2644`,
+   :pr:`2740`,
+   :pr:`2745`)
+-  Overhaul of Filters
+   (:pr:`2759`,
+   :pr:`2922`)
+-  Switch to ``asyncio`` and Refactor PTBs Architecture
+   (:pr:`2731`)
+-  Improve ``Job.__getattr__``
+   (:pr:`2832`)
+-  Remove ``telegram.ReplyMarkup``
+   (:pr:`2870`)
+-  Persistence of ``Bots``: Refactor Automatic Replacement and
+   Integration with ``TelegramObject``
+   (:pr:`2893`)
+
+New Features:
+-------------
+
+-  Introduce Builder Pattern
+   (:pr:`2646`)
+-  Add ``Filters.update.edited``
+   (:pr:`2705`
+   by `PhilippFr <https://github.com/PhilippFr>`__)
+-  Introduce ``Enums`` for ``telegram.constants``
+   (:pr:`2708`)
+-  Accept File Paths for ``private_key``
+   (:pr:`2724`)
+-  Associate ``Jobs`` with ``chat/user_id``
+   (:pr:`2731`)
+-  Convenience Functionality for ``ChatInviteLinks``
+   (:pr:`2782`)
+-  Add ``Dispatcher.add_handlers``
+   (:pr:`2823`)
+-  Improve Error Messages in ``CommandHandler.__init__``
+   (:pr:`2837`)
+-  ``Defaults.protect_content``
+   (:pr:`2840`)
+-  Add ``Dispatcher.migrate_chat_data``
+   (:pr:`2848`
+   by `DonalDuck004 <https://github.com/DonalDuck004>`__)
+-  Add Method ``drop_chat/user_data`` to ``Dispatcher`` and Persistence
+   (:pr:`2852`)
+-  Add methods ``ChatPermissions.{all, no}_permissions`` (:pr:`2948`)
+-  Full Support for API 6.0
+   (:pr:`2956`)
+-  Add Python 3.10 to Test Suite
+   (:pr:`2968`)
+
+Bug Fixes & Minor Changes:
+--------------------------
+
+-  Improve Type Hinting for ``CallbackContext``
+   (:pr:`2587`
+   by `revolter <https://github.com/revolter>`__)
+-  Fix Signatures and Improve ``test_official``
+   (:pr:`2643`)
+-  Refine ``Dispatcher.dispatch_error``
+   (:pr:`2660`)
+-  Make ``InlineQuery.answer`` Raise ``ValueError``
+   (:pr:`2675`)
+-  Improve Signature Inspection for Bot Methods
+   (:pr:`2686`)
+-  Introduce ``TelegramObject.set/get_bot``
+   (:pr:`2712`
+   by `zpavloudis <https://github.com/zpavloudis>`__)
+-  Improve Subscription of ``TelegramObject``
+   (:pr:`2719`
+   by `SimonDamberg <https://github.com/SimonDamberg>`__)
+-  Use Enums for Dynamic Types & Rename Two Attributes in ``ChatMember``
+   (:pr:`2817`)
+-  Return Plain Dicts from ``BasePersistence.get_*_data``
+   (:pr:`2873`)
+-  Fix a Bug in ``ChatMemberUpdated.difference``
+   (:pr:`2947`)
+-  Update Dependency Policy
+   (:pr:`2958`)
+
+Internal Restructurings & Improvements:
+---------------------------------------
+
+-  Add User Friendly Type Check For Init Of
+   ``{Inline, Reply}KeyboardMarkup``
+   (:pr:`2657`)
+-  Warnings Overhaul
+   (:pr:`2662`)
+-  Clear Up Import Policy
+   (:pr:`2671`)
+-  Mark Internal Modules As Private
+   (:pr:`2687`
+   by `kencx <https://github.com/kencx>`__)
+-  Handle Filepaths via the ``pathlib`` Module
+   (:pr:`2688`
+   by `eldbud <https://github.com/eldbud>`__)
+-  Refactor MRO of ``InputMedia*`` and Some File-Like Classes
+   (:pr:`2717`
+   by `eldbud <https://github.com/eldbud>`__)
+-  Update Exceptions for Immutable Attributes
+   (:pr:`2749`)
+-  Refactor Warnings in ``ConversationHandler``
+   (:pr:`2755`,
+   :pr:`2784`)
+-  Use ``__all__`` Consistently
+   (:pr:`2805`)
+
+CI, Code Quality & Test Suite Improvements:
+-------------------------------------------
+
+-  Add Custom ``pytest`` Marker to Ease Development
+   (:pr:`2628`)
+-  Pass Failing Jobs to Error Handlers
+   (:pr:`2692`)
+-  Update Notification Workflows
+   (:pr:`2695`)
+-  Use Error Messages for ``pylint`` Instead of Codes
+   (:pr:`2700`
+   by `Piraty <https://github.com/Piraty>`__)
+-  Make Tests Agnostic of the CWD
+   (:pr:`2727`
+   by `eldbud <https://github.com/eldbud>`__)
+-  Update Code Quality Dependencies
+   (:pr:`2748`)
+-  Improve Code Quality
+   (:pr:`2783`)
+-  Update ``pre-commit`` Settings & Improve a Test
+   (:pr:`2796`)
+-  Improve Code Quality & Test Suite
+   (:pr:`2843`)
+-  Fix failing animation tests
+   (:pr:`2865`)
+-  Update and Expand Tests & pre-commit Settings and Improve Code
+   Quality
+   (:pr:`2925`)
+-  Extend Code Formatting With Black
+   (:pr:`2972`)
+-  Update Workflow Permissions
+   (:pr:`2984`)
+-  Adapt Tests to Changed ``Bot.get_file`` Behavior
+   (:pr:`2995`)
+
+Documentation Improvements:
+---------------------------
+
+-  Doc Fixes
+   (:pr:`2597`)
+-  Add Code Comment Guidelines to Contribution Guide
+   (:pr:`2612`)
+-  Add Cross-References to External Libraries & Other Documentation
+   Improvements
+   (:pr:`2693`,
+   :pr:`2691`
+   by `joesinghh <https://github.com/joesinghh>`__,
+   :pr:`2739`
+   by `eldbud <https://github.com/eldbud>`__)
+-  Use Furo Theme, Make Parameters Referenceable, Add Documentation
+   Building to CI, Improve Links to Source Code & Other Improvements
+   (:pr:`2856`,
+   :pr:`2798`,
+   :pr:`2854`,
+   :pr:`2841`)
+-  Documentation Fixes & Improvements
+   (:pr:`2822`)
+-  Replace ``git.io`` Links
+   (:pr:`2872`
+   by `murugu-21 <https://github.com/murugu-21>`__)
+-  Overhaul Readmes, Update RTD Startpage & Other Improvements
+   (:pr:`2969`)
+
+Version 13.11
+=============
+*Released 2022-02-02*
+
+This is the technical changelog for version 13.11. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+**Major Changes:**
+
+- Full Support for Bot API 5.7 (:pr:`2881`)
+
+Version 13.10
+=============
+*Released 2022-01-03*
+
+This is the technical changelog for version 13.10. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+**Major Changes:**
+
+- Full Support for API 5.6 (:pr:`2835`)
+
+**Minor Changes & Doc fixes:**
+
+- Update Copyright to 2022 (:pr:`2836`)
+- Update Documentation of ``BotCommand`` (:pr:`2820`)
+
+Version 13.9
+============
+*Released 2021-12-11*
+
+This is the technical changelog for version 13.9. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+**Major Changes:**
+
+- Full Support for Api 5.5 (:pr:`2809`)
+
+**Minor Changes**
+
+- Adjust Automated Locking of Inactive Issues (:pr:`2775`)
+
+Version 13.8.1
+==============
+*Released 2021-11-08*
+
+This is the technical changelog for version 13.8.1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+**Doc fixes:**
+
+- Add ``ChatJoinRequest(Handler)`` to Docs (:pr:`2771`)
+
+Version 13.8
+============
+*Released 2021-11-08*
+
+This is the technical changelog for version 13.8. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+**Major Changes:**
+
+- Full support for API 5.4 (:pr:`2767`)
+
+**Minor changes, CI improvements, Doc fixes and Type hinting:**
+
+- Create Issue Template Forms (:pr:`2689`)
+- Fix ``camelCase`` Functions in ``ExtBot`` (:pr:`2659`)
+- Fix Empty Captions not Being Passed by ``Bot.copy_message`` (:pr:`2651`)
+- Fix Setting Thumbs When Uploading A Single File (:pr:`2583`)
+- Fix Bug in ``BasePersistence.insert``/``replace_bot`` for Objects with ``__dict__`` not in ``__slots__`` (:pr:`2603`)
+
+Version 13.7
+============
+*Released 2021-07-01*
+
+This is the technical changelog for version 13.7. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+**Major Changes:**
+
+- Full support for Bot API 5.3 (:pr:`2572`)
+
+**Bug Fixes:**
+
+- Fix Bug in ``BasePersistence.insert/replace_bot`` for Objects with ``__dict__`` in their slots (:pr:`2561`)
+- Remove Incorrect Warning About ``Defaults`` and ``ExtBot`` (:pr:`2553`)
+
+**Minor changes, CI improvements, Doc fixes and Type hinting:**
+
+- Type Hinting Fixes (:pr:`2552`)
+- Doc Fixes (:pr:`2551`)
+- Improve Deprecation Warning for ``__slots__`` (:pr:`2574`)
+- Stabilize CI (:pr:`2575`)
+- Fix Coverage Configuration (:pr:`2571`)
+- Better Exception-Handling for ``BasePersistence.replace/insert_bot`` (:pr:`2564`)
+- Remove Deprecated ``pass_args`` from Deeplinking Example (:pr:`2550`)
+
+Version 13.6
+============
+*Released 2021-06-06*
+
+New Features:
+
+- Arbitrary ``callback_data`` (:pr:`1844`)
+- Add ``ContextTypes`` & ``BasePersistence.refresh_user/chat/bot_data`` (:pr:`2262`)
+- Add ``Filters.attachment`` (:pr:`2528`)
+- Add ``pattern`` Argument to ``ChosenInlineResultHandler`` (:pr:`2517`)
+
+Major Changes:
+
+- Add ``slots`` (:pr:`2345`)
+
+Minor changes, CI improvements, Doc fixes and Type hinting:
+
+- Doc Fixes (:pr:`2495`, :pr:`2510`)
+- Add ``max_connections`` Parameter to ``Updater.start_webhook`` (:pr:`2547`)
+- Fix for ``Promise.done_callback`` (:pr:`2544`)
+- Improve Code Quality (:pr:`2536`, :pr:`2454`)
+- Increase Test Coverage of ``CallbackQueryHandler`` (:pr:`2520`)
+- Stabilize CI (:pr:`2522`, :pr:`2537`, :pr:`2541`)
+- Fix ``send_phone_number_to_provider`` argument for ``Bot.send_invoice`` (:pr:`2527`)
+- Handle Classes as Input for ``BasePersistence.replace/insert_bot`` (:pr:`2523`)
+- Bump Tornado Version and Remove Workaround from :pr:`2067` (:pr:`2494`)
+
+Version 13.5
+============
+*Released 2021-04-30*
+
+**Major Changes:**
+
+- Full support of Bot API 5.2 (:pr:`2489`).
+
+  .. note::
+     The ``start_parameter`` argument of ``Bot.send_invoice`` and the corresponding shortcuts is now optional, so the order of
+     parameters had to be changed. Make sure to update your method calls accordingly.
+
+- Update ``ChatActions``, Deprecating ``ChatAction.RECORD_AUDIO`` and ``ChatAction.UPLOAD_AUDIO`` (:pr:`2460`)
+
+**New Features:**
+
+- Convenience Utilities & Example for Handling ``ChatMemberUpdated`` (:pr:`2490`)
+- ``Filters.forwarded_from`` (:pr:`2446`)
+
+**Minor changes, CI improvements, Doc fixes and Type hinting:**
+
+- Improve Timeouts in ``ConversationHandler`` (:pr:`2417`)
+- Stabilize CI (:pr:`2480`)
+- Doc Fixes (:pr:`2437`)
+- Improve Type Hints of Data Filters (:pr:`2456`)
+- Add Two ``UserWarnings`` (:pr:`2464`)
+- Improve Code Quality (:pr:`2450`)
+- Update Fallback Test-Bots (:pr:`2451`)
+- Improve Examples (:pr:`2441`, :pr:`2448`)
+
+Version 13.4.1
+==============
+*Released 2021-03-14*
+
+**Hot fix release:**
+
+- Fixed a bug in ``setup.py`` (:pr:`2431`)
+
+Version 13.4
+============
+*Released 2021-03-14*
+
+**Major Changes:**
+
+- Full support of Bot API 5.1 (:pr:`2424`)
+
+**Minor changes, CI improvements, doc fixes and type hinting:**
+
+- Improve ``Updater.set_webhook`` (:pr:`2419`)
+- Doc Fixes (:pr:`2404`)
+- Type Hinting Fixes (:pr:`2425`)
+- Update ``pre-commit`` Settings (:pr:`2415`)
+- Fix Logging for Vendored ``urllib3`` (:pr:`2427`)
+- Stabilize Tests (:pr:`2409`)
+
+Version 13.3
+============
+*Released 2021-02-19*
+
+**Major Changes:**
+
+- Make ``cryptography`` Dependency Optional & Refactor Some Tests (:pr:`2386`, :pr:`2370`)
+- Deprecate ``MessageQueue`` (:pr:`2393`)
+
+**Bug Fixes:**
+
+- Refactor ``Defaults`` Integration (:pr:`2363`)
+- Add Missing ``telegram.SecureValue`` to init and Docs (:pr:`2398`)
+
+**Minor changes:**
+
+- Doc Fixes (:pr:`2359`)
+
+Version 13.2
+============
+*Released 2021-02-02*
+
+**Major Changes:**
+
+- Introduce ``python-telegram-bot-raw`` (:pr:`2324`)
+- Explicit Signatures for Shortcuts (:pr:`2240`)
+
+**New Features:**
+
+- Add Missing Shortcuts to ``Message`` (:pr:`2330`)
+- Rich Comparison for ``Bot`` (:pr:`2320`)
+- Add ``run_async`` Parameter to ``ConversationHandler`` (:pr:`2292`)
+- Add New Shortcuts to ``Chat`` (:pr:`2291`)
+- Add New Constant ``MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH`` (:pr:`2282`)
+- Allow Passing Custom Filename For All Media (:pr:`2249`)
+- Handle Bytes as File Input (:pr:`2233`)
+
+**Bug Fixes:**
+
+- Fix Escaping in Nested Entities in ``Message`` Properties (:pr:`2312`)
+- Adjust Calling of ``Dispatcher.update_persistence`` (:pr:`2285`)
+- Add ``quote`` kwarg to ``Message.reply_copy`` (:pr:`2232`)
+- ``ConversationHandler``: Docs & ``edited_channel_post`` behavior (:pr:`2339`)
+
+**Minor changes, CI improvements, doc fixes and type hinting:**
+
+- Doc Fixes (:pr:`2253`, :pr:`2225`)
+- Reduce Usage of ``typing.Any`` (:pr:`2321`)
+- Extend Deeplinking Example (:pr:`2335`)
+- Add pyupgrade to pre-commit Hooks (:pr:`2301`)
+- Add PR Template (:pr:`2299`)
+- Drop Nightly Tests & Update Badges (:pr:`2323`)
+- Update Copyright (:pr:`2289`, :pr:`2287`)
+- Change Order of Class DocStrings (:pr:`2256`)
+- Add macOS to Test Matrix (:pr:`2266`)
+- Start Using Versioning Directives in Docs (:pr:`2252`)
+- Improve Annotations & Docs of Handlers (:pr:`2243`)
+
+Version 13.1
+============
+*Released 2020-11-29*
+
+**Major Changes:**
+
+- Full support of Bot API 5.0 (:pr:`2181`, :pr:`2186`, :pr:`2190`, :pr:`2189`, :pr:`2183`, :pr:`2184`, :pr:`2188`, :pr:`2185`, :pr:`2192`, :pr:`2196`, :pr:`2193`, :pr:`2223`, :pr:`2199`, :pr:`2187`, :pr:`2147`, :pr:`2205`)
+
+**New Features:**
+
+- Add ``Defaults.run_async`` (:pr:`2210`)
+- Improve and Expand ``CallbackQuery`` Shortcuts (:pr:`2172`)
+- Add XOR Filters and make ``Filters.name`` a Property (:pr:`2179`)
+- Add ``Filters.document.file_extension`` (:pr:`2169`)
+- Add ``Filters.caption_regex`` (:pr:`2163`)
+- Add ``Filters.chat_type`` (:pr:`2128`)
+- Handle Non-Binary File Input (:pr:`2202`)
+
+**Bug Fixes:**
+
+- Improve Handling of Custom Objects in ``BasePersistence.insert``/``replace_bot`` (:pr:`2151`)
+- Fix bugs in ``replace/insert_bot`` (:pr:`2218`)
+
+**Minor changes, CI improvements, doc fixes and type hinting:**
+
+- Improve Type hinting (:pr:`2204`, :pr:`2118`, :pr:`2167`, :pr:`2136`)
+- Doc Fixes & Extensions (:pr:`2201`, :pr:`2161`)
+- Use F-Strings Where Possible (:pr:`2222`)
+- Rename kwargs to _kwargs where possible (:pr:`2182`)
+- Comply with PEP561 (:pr:`2168`)
+- Improve Code Quality (:pr:`2131`)
+- Switch Code Formatting to Black (:pr:`2122`, :pr:`2159`, :pr:`2158`)
+- Update Wheel Settings (:pr:`2142`)
+- Update ``timerbot.py`` to ``v13.0`` (:pr:`2149`)
+- Overhaul Constants (:pr:`2137`)
+- Add Python 3.9 to Test Matrix (:pr:`2132`)
+- Switch Codecov to ``GitHub`` Action (:pr:`2127`)
+- Specify Required pytz Version (:pr:`2121`)
+
+Version 13.0
+============
+*Released 2020-10-07*
+
+**For a detailed guide on how to migrate from v12 to v13, see this** `wiki page <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-13.0>`_.
+
+**Major Changes:**
+
+- Deprecate old-style callbacks, i.e. set ``use_context=True`` by default (:pr:`2050`)
+- Refactor Handling of Message VS Update Filters (:pr:`2032`)
+- Deprecate ``Message.default_quote`` (:pr:`1965`)
+- Refactor persistence of Bot instances (:pr:`1994`)
+- Refactor ``JobQueue`` (:pr:`1981`)
+- Refactor handling of kwargs in Bot methods (:pr:`1924`)
+- Refactor ``Dispatcher.run_async``, deprecating the ``@run_async`` decorator (:pr:`2051`)
+
+**New Features:**
+
+- Type Hinting (:pr:`1920`)
+- Automatic Pagination for ``answer_inline_query`` (:pr:`2072`)
+- ``Defaults.tzinfo`` (:pr:`2042`)
+- Extend rich comparison of objects (:pr:`1724`)
+- Add ``Filters.via_bot`` (:pr:`2009`)
+- Add missing shortcuts (:pr:`2043`)
+- Allow ``DispatcherHandlerStop`` in ``ConversationHandler`` (:pr:`2059`)
+- Make Errors picklable (:pr:`2106`)
+
+**Minor changes, CI improvements, doc fixes or bug fixes:**
+
+- Fix Webhook not working on Windows with Python 3.8+ (:pr:`2067`)
+- Fix setting thumbs with ``send_media_group`` (:pr:`2093`)
+- Make ``MessageHandler`` filter for ``Filters.update`` first (:pr:`2085`)
+- Fix ``PicklePersistence.flush()`` with only ``bot_data`` (:pr:`2017`)
+- Add test for clean argument of ``Updater.start_polling/webhook`` (:pr:`2002`)
+- Doc fixes, refinements and additions (:pr:`2005`, :pr:`2008`, :pr:`2089`, :pr:`2094`, :pr:`2090`)
+- CI fixes (:pr:`2018`, :pr:`2061`)
+- Refine ``pollbot.py`` example (:pr:`2047`)
+- Refine Filters in examples (:pr:`2027`)
+- Rename ``echobot`` examples (:pr:`2025`)
+- Use Lock-Bot to lock old threads (:pr:`2048`, :pr:`2052`, :pr:`2049`, :pr:`2053`)
+
+Version 12.8
+============
+*Released 2020-06-22*
+
+**Major Changes:**
+
+- Remove Python 2 support (:pr:`1715`)
+- Bot API 4.9 support (:pr:`1980`)
+- IDs/Usernames of ``Filters.user`` and ``Filters.chat`` can now be updated (:pr:`1757`)
+
+**Minor changes, CI improvements, doc fixes or bug fixes:**
+
+- Update contribution guide and stale bot (:pr:`1937`)
+- Remove ``NullHandlers`` (:pr:`1913`)
+- Improve and expand examples (:pr:`1943`, :pr:`1995`, :pr:`1983`, :pr:`1997`)
+- Doc fixes (:pr:`1940`, :pr:`1962`)
+- Add ``User.send_poll()`` shortcut (:pr:`1968`)
+- Ignore private attributes en ``TelegramObject.to_dict()`` (:pr:`1989`)
+- Stabilize CI (:pr:`2000`)
+
+Version 12.7
+============
+*Released 2020-05-02*
+
+**Major Changes:**
+
+- Bot API 4.8 support. **Note:** The ``Dice`` object now has a second positional argument ``emoji``. This is relevant, if you instantiate ``Dice`` objects manually. (:pr:`1917`)
+- Added ``tzinfo`` argument to ``helpers.from_timestamp``. It now returns an timezone aware object. This is relevant for ``Message.{date,forward_date,edit_date}``, ``Poll.close_date`` and ``ChatMember.until_date`` (:pr:`1621`)
+
+**New Features:**
+
+- New method ``run_monthly`` for the ``JobQueue`` (:pr:`1705`)
+- ``Job.next_t`` now gives the datetime of the jobs next execution (:pr:`1685`)
+
+**Minor changes, CI improvements, doc fixes or bug fixes:**
+
+- Stabalize CI (:pr:`1919`, :pr:`1931`)
+- Use ABCs ``@abstractmethod`` instead of raising ``NotImplementedError`` for ``Handler``, ``BasePersistence`` and ``BaseFilter`` (:pr:`1905`)
+- Doc fixes (:pr:`1914`, :pr:`1902`, :pr:`1910`)
+
+Version 12.6.1
+==============
+*Released 2020-04-11*
+
+**Bug fixes:**
+
+- Fix serialization of ``reply_markup`` in media messages (:pr:`1889`)
+
+Version 12.6
+============
+*Released 2020-04-10*
+
+**Major Changes:**
+
+- Bot API 4.7 support. **Note:** In ``Bot.create_new_sticker_set`` and ``Bot.add_sticker_to_set``, the order of the parameters had be changed, as the ``png_sticker`` parameter is now optional. (:pr:`1858`)
+
+**Minor changes, CI improvements or bug fixes:**
+
+- Add tests for ``swtich_inline_query(_current_chat)`` with empty string (:pr:`1635`)
+- Doc fixes (:pr:`1854`, :pr:`1874`, :pr:`1884`)
+- Update issue templates (:pr:`1880`)
+- Favor concrete types over "Iterable" (:pr:`1882`)
+- Pass last valid ``CallbackContext`` to ``TIMEOUT`` handlers of ``ConversationHandler`` (:pr:`1826`)
+- Tweak handling of persistence and update persistence after job calls (:pr:`1827`)
+- Use checkout@v2 for GitHub actions (:pr:`1887`)
+
+Version 12.5.1
+==============
+*Released 2020-03-30*
+
+**Minor changes, doc fixes or bug fixes:**
+
+- Add missing docs for `PollHandler` and `PollAnswerHandler` (:pr:`1853`)
+- Fix wording in `Filters` docs (:pr:`1855`)
+- Reorder tests to make them more stable (:pr:`1835`)
+- Make `ConversationHandler` attributes immutable (:pr:`1756`)
+- Make `PrefixHandler` attributes `command` and `prefix` editable (:pr:`1636`)
+- Fix UTC as default `tzinfo` for `Job` (:pr:`1696`)
+
+Version 12.5
+============
+*Released 2020-03-29*
+
+**New Features:**
+
+- `Bot.link` gives the `t.me` link of the bot (:pr:`1770`)
+
+**Major Changes:**
+
+- Bot API 4.5 and 4.6 support. (:pr:`1508`, :pr:`1723`)
+
+**Minor changes, CI improvements or bug fixes:**
+
+- Remove legacy CI files (:pr:`1783`, :pr:`1791`)
+- Update pre-commit config file (:pr:`1787`)
+- Remove builtin names (:pr:`1792`)
+- CI improvements (:pr:`1808`, :pr:`1848`)
+- Support Python 3.8 (:pr:`1614`, :pr:`1824`)
+- Use stale bot for auto closing stale issues (:pr:`1820`, :pr:`1829`, :pr:`1840`)
+- Doc fixes (:pr:`1778`, :pr:`1818`)
+- Fix typo in `edit_message_media` (:pr:`1779`)
+- In examples, answer CallbackQueries and use `edit_message_text` shortcut (:pr:`1721`)
+- Revert accidental change in vendored urllib3 (:pr:`1775`)
+
+Version 12.4.2
+==============
+*Released 2020-02-10*
+
+**Bug Fixes**
+
+- Pass correct parse_mode to InlineResults if bot.defaults is None (:pr:`1763`)
+- Make sure PP can read files that dont have bot_data (:pr:`1760`)
+
+Version 12.4.1
+==============
+*Released 2020-02-08*
+
+This is a quick release for :pr:`1744` which was accidently left out of v12.4.0 though mentioned in the
+release notes.
+
+Version 12.4.0
+==============
+*Released 2020-02-08*
+
+**New features:**
+
+- Set default values for arguments appearing repeatedly. We also have a `wiki page for the new defaults`_. (:pr:`1490`)
+- Store data in ``CallbackContext.bot_data`` to access it in every callback. Also persists. (:pr:`1325`)
+- ``Filters.poll`` allows only messages containing a poll (:pr:`1673`)
+
+**Major changes:**
+
+- ``Filters.text`` now accepts messages that start with a slash, because ``CommandHandler`` checks for ``MessageEntity.BOT_COMMAND`` since v12. This might lead to your MessageHandlers receiving more updates than before (:pr:`1680`).
+- ``Filters.command`` new checks for ``MessageEntity.BOT_COMMAND`` instead of just a leading slash. Also by ``Filters.command(False)`` you can now filters for messages containing a command `anywhere` in the text (:pr:`1744`).
+
+**Minor changes, CI improvements or bug fixes:**
+
+- Add ``disptacher`` argument to ``Updater`` to allow passing a customized ``Dispatcher`` (:pr:`1484`)
+- Add missing names for ``Filters`` (:pr:`1632`)
+- Documentation fixes (:pr:`1624`, :pr:`1647`, :pr:`1669`, :pr:`1703`, :pr:`1718`, :pr:`1734`, :pr:`1740`, :pr:`1642`, :pr:`1739`, :pr:`1746`)
+- CI improvements (:pr:`1716`, :pr:`1731`, :pr:`1738`, :pr:`1748`, :pr:`1749`, :pr:`1750`, :pr:`1752`)
+- Fix spelling issue for ``encode_conversations_to_json`` (:pr:`1661`)
+- Remove double assignement of ``Dispatcher.job_queue`` (:pr:`1698`)
+- Expose dispatcher as property for ``CallbackContext`` (:pr:`1684`)
+- Fix ``None`` check in ``JobQueue._put()`` (:pr:`1707`)
+- Log datetimes correctly in ``JobQueue`` (:pr:`1714`)
+- Fix false ``Message.link`` creation for private groups (:pr:`1741`)
+- Add option ``--with-upstream-urllib3`` to `setup.py` to allow using non-vendored version (:pr:`1725`)
+- Fix persistence for nested ``ConversationHandlers`` (:pr:`1679`)
+- Improve handling of non-decodable server responses (:pr:`1623`)
+- Fix download for files without ``file_path`` (:pr:`1591`)
+- test_webhook_invalid_posts is now considered flaky and retried on failure (:pr:`1758`)
+
+.. _`wiki page for the new defaults`: https://github.com/python-telegram-bot/python-telegram-bot/wiki/Adding-defaults-to-your-bot
+
+Version 12.3.0
+==============
+*Released 2020-01-11*
+
+**New features:**
+
+- `Filters.caption` allows only messages with caption (:pr:`1631`).
+- Filter for exact messages/captions with new capability of `Filters.text` and `Filters.caption`. Especially useful in combination with ReplyKeyboardMarkup. (:pr:`1631`).
+
+**Major changes:**
+
+- Fix inconsistent handling of naive datetimes (:pr:`1506`).
+
+**Minor changes, CI improvements or bug fixes:**
+
+- Documentation fixes (:pr:`1558`, :pr:`1569`, :pr:`1579`, :pr:`1572`, :pr:`1566`, :pr:`1577`, :pr:`1656`).
+- Add mutex protection on `ConversationHandler` (:pr:`1533`).
+- Add `MAX_PHOTOSIZE_UPLOAD` constant (:pr:`1560`).
+- Add args and kwargs to `Message.forward()` (:pr:`1574`).
+- Transfer to GitHub Actions CI (:pr:`1555`, :pr:`1556`, :pr:`1605`, :pr:`1606`, :pr:`1607`, :pr:`1612`, :pr:`1615`, :pr:`1645`).
+- Fix deprecation warning with Py3.8 by vendored urllib3 (:pr:`1618`).
+- Simplify assignements for optional arguments (:pr:`1600`)
+- Allow private groups for `Message.link` (:pr:`1619`).
+- Fix wrong signature call for `ConversationHandler.TIMEOUT` handlers (:pr:`1653`).
+
+Version 12.2.0
+==============
+*Released 2019-10-14*
+
+**New features:**
+
+- Nested ConversationHandlers (:pr:`1512`).
+
+**Minor changes, CI improvments or bug fixes:**
+
+- Fix CI failures due to non-backward compat attrs depndency (:pr:`1540`).
+- travis.yaml: TEST_OFFICIAL removed from allowed_failures.
+- Fix typos in examples (:pr:`1537`).
+- Fix Bot.to_dict to use proper first_name (:pr:`1525`).
+- Refactor ``test_commandhandler.py`` (:pr:`1408`).
+- Add Python 3.8 (RC version) to Travis testing matrix (:pr:`1543`).
+- test_bot.py: Add to_dict test (:pr:`1544`).
+- Flake config moved into setup.cfg (:pr:`1546`).
+
+Version 12.1.1
+==============
+*Released 2019-09-18*
+
+**Hot fix release**
+
+Fixed regression in the vendored urllib3 (:pr:`1517`).
+
+Version 12.1.0
+================
+*Released 2019-09-13*
+
+**Major changes:**
+
+- Bot API 4.4 support (:pr:`1464`, :pr:`1510`)
+- Add `get_file` method to `Animation` & `ChatPhoto`. Add, `get_small_file` & `get_big_file`
+  methods to `ChatPhoto` (:pr:`1489`)
+- Tools for deep linking (:pr:`1049`)
+
+**Minor changes and/or bug fixes:**
+
+- Documentation fixes (:pr:`1500`, :pr:`1499`)
+- Improved examples (:pr:`1502`)
+
+Version 12.0.0
+================
+*Released 2019-08-29*
+
+Well... This felt like decades. But here we are with a new release.
+
+Expect minor releases soon (mainly complete Bot API 4.4 support)
+
+**Major and/or breaking changes:**
+
+- Context based callbacks
+- Persistence
+- PrefixHandler added (Handler overhaul)
+- Deprecation of RegexHandler and edited_messages, channel_post, etc. arguments (Filter overhaul)
+- Various ConversationHandler changes and fixes
+- Bot API 4.1, 4.2, 4.3 support
+- Python 3.4 is no longer supported
+- Error Handler now handles all types of exceptions (:pr:`1485`)
+- Return UTC from from_timestamp() (:pr:`1485`)
+
+**See the wiki page at https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-12.0 for a detailed guide on how to migrate from version 11 to version 12.**
+
+Context based callbacks (:pr:`1100`)
+------------------------------------
+
+- Use of ``pass_`` in handlers is deprecated.
+- Instead use ``use_context=True`` on ``Updater`` or ``Dispatcher`` and change callback from (bot, update, others...) to (update, context).
+- This also applies to error handlers ``Dispatcher.add_error_handler`` and JobQueue jobs (change (bot, job) to (context) here).
+- For users with custom handlers subclassing Handler, this is mostly backwards compatible, but to use the new context based callbacks you need to implement the new collect_additional_context method.
+- Passing bot to ``JobQueue.__init__`` is deprecated. Use JobQueue.set_dispatcher with a dispatcher instead.
+- Dispatcher makes sure to use a single `CallbackContext` for a entire update. This means that if an update is handled by multiple handlers (by using the group argument), you can add custom arguments to the `CallbackContext` in a lower group handler and use it in higher group handler. NOTE: Never use with @run_async, see docs for more info. (:pr:`1283`)
+- If you have custom handlers they will need to be updated to support the changes in this release.
+- Update all examples to use context based callbacks.
+
+Persistence (:pr:`1017`)
+------------------------
+
+- Added PicklePersistence and DictPersistence for adding persistence to your bots.
+- BasePersistence can be subclassed for all your persistence needs.
+- Add a new example that shows a persistent ConversationHandler bot
+
+Handler overhaul (:pr:`1114`)
+-----------------------------
+
+- CommandHandler now only triggers on actual commands as defined by telegram servers (everything that the clients mark as a tabable link).
+- PrefixHandler can be used if you need to trigger on prefixes (like all messages starting with a "/" (old CommandHandler behaviour) or even custom prefixes like "#" or "!").
+
+Filter overhaul (:pr:`1221`)
+----------------------------
+
+- RegexHandler is deprecated and should be replaced with a MessageHandler with a regex filter.
+- Use update filters to filter update types instead of arguments (message_updates, channel_post_updates and edited_updates) on the handlers.
+- Completely remove allow_edited argument - it has been deprecated for a while.
+- data_filters now exist which allows filters that return data into the callback function. This is how the regex filter is implemented.
+- All this means that it no longer possible to use a list of filters in a handler. Use bitwise operators instead!
+
+ConversationHandler
+-------------------
+
+- Remove ``run_async_timeout`` and ``timed_out_behavior`` arguments (:pr:`1344`)
+- Replace with ``WAITING`` constant and behavior from states (:pr:`1344`)
+- Only emit one warning for multiple CallbackQueryHandlers in a ConversationHandler (:pr:`1319`)
+- Use warnings.warn for ConversationHandler warnings (:pr:`1343`)
+- Fix unresolvable promises (:pr:`1270`)
+
+Bug fixes & improvements
+------------------------
+
+- Handlers should be faster due to deduped logic.
+- Avoid compiling compiled regex in regex filter. (:pr:`1314`)
+- Add missing ``left_chat_member`` to Message.MESSAGE_TYPES (:pr:`1336`)
+- Make custom timeouts actually work properly (:pr:`1330`)
+- Add convenience classmethods (from_button, from_row and from_column) to InlineKeyboardMarkup
+- Small typo fix in setup.py (:pr:`1306`)
+- Add Conflict error (HTTP error code 409) (:pr:`1154`)
+- Change MAX_CAPTION_LENGTH to 1024 (:pr:`1262`)
+- Remove some unnecessary clauses (:pr:`1247`, :pr:`1239`)
+- Allow filenames without dots in them when sending files (:pr:`1228`)
+- Fix uploading files with unicode filenames (:pr:`1214`)
+- Replace http.server with Tornado (:pr:`1191`)
+- Allow SOCKSConnection to parse username and password from URL (:pr:`1211`)
+- Fix for arguments in passport/data.py (:pr:`1213`)
+- Improve message entity parsing by adding text_mention (:pr:`1206`)
+- Documentation fixes (:pr:`1348`, :pr:`1397`, :pr:`1436`)
+- Merged filters short-circuit (:pr:`1350`)
+- Fix webhook listen with tornado (:pr:`1383`)
+- Call task_done() on update queue after update processing finished (:pr:`1428`)
+- Fix send_location() - latitude may be 0 (:pr:`1437`)
+- Make MessageEntity objects comparable (:pr:`1465`)
+- Add prefix to thread names (:pr:`1358`)
+
+Buf fixes since v12.0.0b1
+-------------------------
+
+- Fix setting bot on ShippingQuery (:pr:`1355`)
+- Fix _trigger_timeout() missing 1 required positional argument: 'job' (:pr:`1367`)
+- Add missing message.text check in PrefixHandler check_update (:pr:`1375`)
+- Make updates persist even on DispatcherHandlerStop (:pr:`1463`)
+- Dispatcher force updating persistence object's chat data attribute(:pr:`1462`)
+
+Internal improvements
+---------------------
+
+- Finally fix our CI builds mostly (too many commits and PRs to list)
+- Use multiple bots for CI to improve testing times significantly.
+- Allow pypy to fail in CI.
+- Remove the last CamelCase CheckUpdate methods from the handlers we missed earlier.
+- test_official is now executed in a different job
+
+Version 11.1.0
+==============
+*Released 2018-09-01*
+
+Fixes and updates for Telegram Passport: (:pr:`1198`)
+
+- Fix passport decryption failing at random times
+- Added support for middle names.
+- Added support for translations for documents
+- Add errors for translations for documents
+- Added support for requesting names in the language of the user's country of residence
+- Replaced the payload parameter with the new parameter nonce
+- Add hash to EncryptedPassportElement
+
+Version 11.0.0
+==============
+*Released 2018-08-29*
+
+Fully support Bot API version 4.0!
+(also some bugfixes :))
+
+Telegram Passport (:pr:`1174`):
+
+- Add full support for telegram passport.
+    - New types: PassportData, PassportFile, EncryptedPassportElement, EncryptedCredentials, PassportElementError, PassportElementErrorDataField, PassportElementErrorFrontSide, PassportElementErrorReverseSide, PassportElementErrorSelfie, PassportElementErrorFile and PassportElementErrorFiles.
+    - New bot method: set_passport_data_errors
+    - New filter: Filters.passport_data
+    - Field passport_data field on Message
+    - PassportData can be easily decrypted.
+    - PassportFiles are automatically decrypted if originating from decrypted PassportData.
+- See new passportbot.py example for details on how to use, or go to `our telegram passport wiki page`_ for more info
+- NOTE: Passport decryption requires new dependency `cryptography`.
+
+Inputfile rework (:pr:`1184`):
+
+- Change how Inputfile is handled internally
+- This allows support for specifying the thumbnails of photos and videos using the thumb= argument in the different send\_ methods.
+- Also allows Bot.send_media_group to actually finally send more than one media.
+- Add thumb to Audio, Video and Videonote
+- Add Bot.edit_message_media together with InputMediaAnimation, InputMediaAudio, and inputMediaDocument.
+
+Other Bot API 4.0 changes:
+
+- Add forusquare_type to Venue, InlineQueryResultVenue, InputVenueMessageContent, and Bot.send_venue. (:pr:`1170`)
+- Add vCard support by adding vcard field to Contact, InlineQueryResultContact, InputContactMessageContent, and Bot.send_contact. (:pr:`1166`)
+- Support new message entities: CASHTAG and PHONE_NUMBER. (:pr:`1179`)
+    - Cashtag seems to be things like `$USD` and `$GBP`, but it seems telegram doesn't currently send them to bots.
+    - Phone number also seems to have limited support for now
+- Add Bot.send_animation, add width, height, and duration to Animation, and add Filters.animation. (:pr:`1172`)
+
+Non Bot API 4.0 changes:
+
+- Minor integer comparison fix (:pr:`1147`)
+- Fix Filters.regex failing on non-text message (:pr:`1158`)
+- Fix ProcessLookupError if process finishes before we kill it (:pr:`1126`)
+- Add t.me links for User, Chat and Message if available and update User.mention_* (:pr:`1092`)
+- Fix mention_markdown/html on py2 (:pr:`1112`)
+
+.. _`our telegram passport wiki page`: https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport
+
+Version 10.1.0
+==============
+*Released 2018-05-02*
+
+Fixes changing previous behaviour:
+
+- Add urllib3 fix for socks5h support (:pr:`1085`)
+- Fix send_sticker() timeout=20 (:pr:`1088`)
+
+Fixes:
+
+- Add a caption_entity filter for filtering caption entities (:pr:`1068`)
+- Inputfile encode filenames (:pr:`1086`)
+- InputFile: Fix proper naming of file when reading from subprocess.PIPE (:pr:`1079`)
+- Remove pytest-catchlog from requirements (:pr:`1099`)
+- Documentation fixes (:pr:`1061`, :pr:`1078`, :pr:`1081`, :pr:`1096`)
+
+Version 10.0.2
+==============
+*Released 2018-04-17*
+
+Important fix:
+
+- Handle utf8 decoding errors (:pr:`1076`)
+
+New features:
+
+- Added Filter.regex (:pr:`1028`)
+- Filters for Category and file types (:pr:`1046`)
+- Added video note filter (:pr:`1067`)
+
+Fixes:
+
+- Fix in telegram.Message (:pr:`1042`)
+- Make chat_id a positional argument inside shortcut methods of Chat and User classes (:pr:`1050`)
+- Make Bot.full_name return a unicode object. (:pr:`1063`)
+- CommandHandler faster check (:pr:`1074`)
+- Correct documentation of Dispatcher.add_handler (:pr:`1071`)
+- Various small fixes to documentation.
+
+Version 10.0.1
+==============
+*Released 2018-03-05*
+
+Fixes:
+
+- Fix conversationhandler timeout (PR :pr:`1032`)
+- Add missing docs utils (PR :pr:`912`)
+
+Version 10.0.0
+==============
+*Released 2018-03-02*
+
+Non backward compatabile changes and changed defaults
+
+- JobQueue: Remove deprecated prevent_autostart & put() (PR :pr:`1012`)
+- Bot, Updater: Remove deprecated network_delay (PR :pr:`1012`)
+- Remove deprecated Message.new_chat_member (PR :pr:`1012`)
+- Retry bootstrap phase indefinitely (by default) on network errors (PR :pr:`1018`)
+
+New Features
+
+- Support v3.6 API (PR :pr:`1006`)
+- User.full_name convinience property (PR :pr:`949`)
+- Add `send_phone_number_to_provider` and `send_email_to_provider` arguments to send_invoice (PR :pr:`986`)
+- Bot: Add shortcut methods reply_{markdown,html} (PR :pr:`827`)
+- Bot: Add shortcut method reply_media_group (PR :pr:`994`)
+- Added utils.helpers.effective_message_type (PR :pr:`826`)
+- Bot.get_file now allows passing a file in addition to file_id (PR :pr:`963`)
+- Add .get_file() to Audio, Document, PhotoSize, Sticker, Video, VideoNote and Voice (PR :pr:`963`)
+- Add .send_*() methods to User and Chat (PR :pr:`963`)
+- Get jobs by name (PR :pr:`1011`)
+- Add Message caption html/markdown methods (PR :pr:`1013`)
+- File.download_as_bytearray - new method to get a d/led file as bytearray (PR :pr:`1019`)
+- File.download(): Now returns a meaningful return value (PR :pr:`1019`)
+- Added conversation timeout in ConversationHandler (PR :pr:`895`)
+
+Changes
+
+- Store bot in PreCheckoutQuery (PR :pr:`953`)
+- Updater: Issue INFO log upon received signal (PR :pr:`951`)
+- JobQueue: Thread safety fixes (PR :pr:`977`)
+- WebhookHandler: Fix exception thrown during error handling (PR :pr:`985`)
+- Explicitly check update.effective_chat in ConversationHandler.check_update (PR :pr:`959`)
+- Updater: Better handling of timeouts during get_updates (PR :pr:`1007`)
+- Remove unnecessary to_dict() (PR :pr:`834`)
+- CommandHandler - ignore strings in entities and "/" followed by whitespace (PR :pr:`1020`)
+- Documentation & style fixes (PR :pr:`942`, PR :pr:`956`, PR :pr:`962`, PR :pr:`980`, PR :pr:`983`)
+
+Version 9.0.0
+=============
+*Released 2017-12-08*
+
+Breaking changes (possibly)
+
+- Drop support for python 3.3 (PR :pr:`930`)
+
+New Features
+
+- Support Bot API 3.5 (PR :pr:`920`)
+
+Changes
+
+- Fix race condition in dispatcher start/stop (:pr:`887`)
+- Log error trace if there is no error handler registered (:pr:`694`)
+- Update examples with consistent string formatting (:pr:`870`)
+- Various changes and improvements to the docs.
+
+Version 8.1.1
+=============
+*Released 2017-10-15*
+
+- Fix Commandhandler crashing on single character messages (PR :pr:`873`).
+
+Version 8.1.0
+=============
+*Released 2017-10-14*
+
+New features
+- Support Bot API 3.4 (PR :pr:`865`).
+
+Changes
+- MessageHandler & RegexHandler now consider channel_updates.
+- Fix command not recognized if it is directly followed by a newline (PR :pr:`869`).
+- Removed Bot._message_wrapper (PR :pr:`822`).
+- Unitests are now also running on AppVeyor (Windows VM).
+- Various unitest improvements.
+- Documentation fixes.
+
+Version 8.0.0
+=============
+*Released 2017-09-01*
+
+New features
+
+- Fully support Bot Api 3.3 (PR :pr:`806`).
+- DispatcherHandlerStop (`see docs`_).
+- Regression fix for text_html & text_markdown (PR :pr:`777`).
+- Added effective_attachment to message (PR :pr:`766`).
+
+Non backward compatible changes
+
+- Removed Botan support from the library  (PR :pr:`776`).
+- Fully support Bot Api 3.3 (PR :pr:`806`).
+- Remove de_json() (PR :pr:`789`).
+
+Changes
+
+- Sane defaults for tcp socket options on linux (PR :pr:`754`).
+- Add RESTRICTED as constant to ChatMember (PR :pr:`761`).
+- Add rich comparison to CallbackQuery (PR :pr:`764`).
+- Fix get_game_high_scores (PR :pr:`771`).
+- Warn on small con_pool_size during custom initalization of Updater (PR :pr:`793`).
+- Catch exceptions in error handlerfor errors that happen during polling (PR :pr:`810`).
+- For testing we switched to pytest (PR :pr:`788`).
+- Lots of small improvements to our tests and documentation.
+
+.. _`see docs`: https://docs.python-telegram-bot.org/en/v13.11/telegram.ext.dispatcher.html?highlight=Dispatcher.add_handler#telegram.ext.Dispatcher.add_handler
+
+Version 7.0.1
+===============
+*Released 2017-07-28*
+
+- Fix TypeError exception in RegexHandler (PR #751).
+- Small documentation fix (PR #749).
+
+Version 7.0.0
+=============
+*Released 2017-07-25*
+
+- Fully support Bot API 3.2.
+- New filters for handling messages from specific chat/user id (PR #677).
+- Add the possibility to add objects as arguments to send_* methods (PR #742).
+- Fixed download of URLs with UTF-8 chars in path (PR #688).
+- Fixed URL parsing for ``Message`` text properties (PR #689).
+- Fixed args dispatching in ``MessageQueue``'s decorator (PR #705).
+- Fixed regression preventing IPv6 only hosts from connnecting to Telegram servers (Issue #720).
+- ConvesationHandler - check if a user exist before using it (PR #699).
+- Removed deprecated ``telegram.Emoji``.
+- Removed deprecated ``Botan`` import from ``utils`` (``Botan`` is still available through ``contrib``).
+- Removed deprecated ``ReplyKeyboardHide``.
+- Removed deprecated ``edit_message`` argument of ``bot.set_game_score``.
+- Internal restructure of files.
+- Improved documentation.
+- Improved unitests.
+
+Pre-version 7.0
+===============
+
+**2017-06-18**
+
+*Released 6.1.0*
+
+- Fully support Bot API 3.0
+- Add more fine-grained filters for status updates
+- Bug fixes and other improvements
+
+**2017-05-29**
+
+*Released 6.0.3*
+
+- Faulty PyPI release
+
+**2017-05-29**
+
+*Released 6.0.2*
+
+- Avoid confusion with user's ``urllib3`` by renaming vendored ``urllib3`` to ``ptb_urllib3``
+
+**2017-05-19**
+
+*Released 6.0.1*
+
+- Add support for ``User.language_code``
+- Fix ``Message.text_html`` and ``Message.text_markdown`` for messages with emoji
+
+**2017-05-19**
+
+*Released 6.0.0*
+
+- Add support for Bot API 2.3.1
+- Add support for ``deleteMessage`` API method
+- New, simpler API for ``JobQueue`` - :pr:`484`
+- Download files into file-like objects - :pr:`459`
+- Use vendor ``urllib3`` to address issues with timeouts
+  - The default timeout for messages is now 5 seconds. For sending media, the default timeout is now 20 seconds.
+- String attributes that are not set are now ``None`` by default, instead of empty strings
+- Add ``text_markdown`` and ``text_html`` properties to ``Message`` - :pr:`507`
+- Add support for Socks5 proxy - :pr:`518`
+- Add support for filters in ``CommandHandler`` - :pr:`536`
+- Add the ability to invert (not) filters - :pr:`552`
+- Add ``Filters.group`` and ``Filters.private``
+- Compatibility with GAE via ``urllib3.contrib`` package - :pr:`583`
+- Add equality rich comparision operators to telegram objects - :pr:`604`
+- Several bugfixes and other improvements
+- Remove some deprecated code
+
+**2017-04-17**
+
+*Released 5.3.1*
+
+- Hotfix release due to bug introduced by urllib3 version 1.21
+
+**2016-12-11**
+
+*Released 5.3*
+
+- Implement API changes of November 21st (Bot API 2.3)
+- ``JobQueue`` now supports ``datetime.timedelta`` in addition to seconds
+- ``JobQueue`` now supports running jobs only on certain days
+- New ``Filters.reply`` filter
+- Bugfix for ``Message.edit_reply_markup``
+- Other bugfixes
+
+**2016-10-25**
+
+*Released 5.2*
+
+- Implement API changes of October 3rd (games update)
+- Add ``Message.edit_*`` methods
+- Filters for the ``MessageHandler`` can now be combined using bitwise operators (``& and |``)
+- Add a way to save user- and chat-related data temporarily
+- Other bugfixes and improvements
+
+**2016-09-24**
+
+*Released 5.1*
+
+- Drop Python 2.6 support
+- Deprecate ``telegram.Emoji``
+
+- Use ``ujson`` if available
+- Add instance methods to ``Message``, ``Chat``, ``User``, ``InlineQuery`` and ``CallbackQuery``
+- RegEx filtering for ``CallbackQueryHandler`` and ``InlineQueryHandler``
+- New ``MessageHandler`` filters: ``forwarded`` and ``entity``
+- Add ``Message.get_entity`` to correctly handle UTF-16 codepoints and ``MessageEntity`` offsets
+- Fix bug in ``ConversationHandler`` when first handler ends the conversation
+- Allow multiple ``Dispatcher`` instances
+- Add ``ChatMigrated`` Exception
+- Properly split and handle arguments in ``CommandHandler``
+
+**2016-07-15**
+
+*Released 5.0*
+
+- Rework ``JobQueue``
+- Introduce ``ConversationHandler``
+- Introduce ``telegram.constants`` - :pr:`342`
+
+**2016-07-12**
+
+*Released 4.3.4*
+
+- Fix proxy support with ``urllib3`` when proxy requires auth
+
+**2016-07-08**
+
+*Released 4.3.3*
+
+- Fix proxy support with ``urllib3``
+
+**2016-07-04**
+
+*Released 4.3.2*
+
+- Fix: Use ``timeout`` parameter in all API methods
+
+**2016-06-29**
+
+*Released 4.3.1*
+
+- Update wrong requirement: ``urllib3>=1.10``
+
+**2016-06-28**
+
+*Released 4.3*
+
+- Use ``urllib3.PoolManager`` for connection re-use
+- Rewrite ``run_async`` decorator to re-use threads
+- New requirements: ``urllib3`` and ``certifi``
+
+**2016-06-10**
+
+*Released 4.2.1*
+
+- Fix ``CallbackQuery.to_dict()`` bug (thanks to @jlmadurga)
+- Fix ``editMessageText`` exception when receiving a ``CallbackQuery``
+
+**2016-05-28**
+
+*Released 4.2*
+
+- Implement Bot API 2.1
+- Move ``botan`` module to ``telegram.contrib``
+- New exception type: ``BadRequest``
+
+**2016-05-22**
+
+*Released 4.1.2*
+
+- Fix ``MessageEntity`` decoding with Bot API 2.1 changes
+
+**2016-05-16**
+
+*Released 4.1.1*
+
+- Fix deprecation warning in ``Dispatcher``
+
+**2016-05-15**
+
+*Released 4.1*
+
+- Implement API changes from May 6, 2016
+- Fix bug when ``start_polling`` with ``clean=True``
+- Methods now have snake_case equivalent, for example ``telegram.Bot.send_message`` is the same as ``telegram.Bot.sendMessage``
+
+**2016-05-01**
+
+*Released 4.0.3*
+
+- Add missing attribute ``location`` to ``InlineQuery``
+
+**2016-04-29**
+
+*Released 4.0.2*
+
+- Bugfixes
+- ``KeyboardReplyMarkup`` now accepts ``str`` again
+
+**2016-04-27**
+
+*Released 4.0.1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- Please read the `Transition Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-4.0>`_
+- **Changes from 4.0rc1**
+    - The syntax of filters for ``MessageHandler`` (upper/lower cases)
+    - Handler groups are now identified by ``int`` only, and ordered
+- **Note:** v4.0 has been skipped due to a PyPI accident
+
+**2016-04-22**
+
+*Released 4.0rc1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- 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**
+
+*Released 3.4*
+
+- Move ``Updater``, ``Dispatcher`` and ``JobQueue`` to new ``telegram.ext`` submodule (thanks to @rahiel)
+- Add ``disable_notification`` parameter (thanks to @aidarbiktimirov)
+- Fix bug where commands sent by Telegram Web would not be recognized (thanks to @shelomentsevd)
+- Add option to skip old updates on bot startup
+- Send files from ``BufferedReader``
+
+**2016-02-28**
+
+*Released 3.3*
+
+- Inline bots
+- Send any file by URL
+- Specialized exceptions: ``Unauthorized``, ``InvalidToken``, ``NetworkError`` and ``TimedOut``
+- Integration for botan.io (thanks to @ollmer)
+- HTML Parsemode (thanks to @jlmadurga)
+- Bugfixes and under-the-hood improvements
+
+**Very special thanks to Noam Meltzer (@tsnoam) for all of his work!**
+
+**2016-01-09**
+
+*Released 3.3b1*
+
+- Implement inline bots (beta)
+
+**2016-01-05**
+
+*Released 3.2.0*
+
+- Introducing ``JobQueue`` (original author: @franciscod)
+- Streamlining all exceptions to ``TelegramError`` (Special thanks to @tsnoam)
+- Proper locking of ``Updater`` and ``Dispatcher`` ``start`` and ``stop`` methods
+- Small bugfixes
+
+**2015-12-29**
+
+*Released 3.1.2*
+
+- Fix custom path for file downloads
+- Don't stop the dispatcher thread on uncaught errors in handlers
+
+**2015-12-21**
+
+*Released 3.1.1*
+
+- Fix a bug where asynchronous handlers could not have additional arguments
+- Add ``groups`` and ``groupdict`` as additional arguments for regex-based handlers
+
+**2015-12-16**
+
+*Released 3.1.0*
+
+- The ``chat``-field in ``Message`` is now of type ``Chat``. (API update Oct 8 2015)
+- ``Message`` now contains the optional fields ``supergroup_chat_created``, ``migrate_to_chat_id``, ``migrate_from_chat_id`` and ``channel_chat_created``. (API update Nov 2015)
+
+**2015-12-08**
+
+*Released 3.0.0*
+
+- Introducing the ``Updater`` and ``Dispatcher`` classes
+
+**2015-11-11**
+
+*Released 2.9.2*
+
+- Error handling on request timeouts has been improved
+
+**2015-11-10**
+
+*Released 2.9.1*
+
+- Add parameter ``network_delay`` to Bot.getUpdates for slow connections
+
+**2015-11-10**
+
+*Released 2.9*
+
+- Emoji class now uses ``bytes_to_native_str`` from ``future`` 3rd party lib
+- Make ``user_from`` optional to work with channels
+- Raise exception if Telegram times out on long-polling
+
+*Special thanks to @jh0ker for all hard work*
+
+**2015-10-08**
+
+*Released 2.8.7*
+
+- Type as optional for ``GroupChat`` class
+
+**2015-10-08**
+
+*Released 2.8.6*
+
+- Adds type to ``User`` and ``GroupChat`` classes (pre-release Telegram feature)
+
+**2015-09-24**
+
+*Released 2.8.5*
+
+- Handles HTTP Bad Gateway (503) errors on request
+- Fixes regression on ``Audio`` and ``Document`` for unicode fields
+
+**2015-09-20**
+
+*Released 2.8.4*
+
+- ``getFile`` and ``File.download`` is now fully supported
+
+**2015-09-10**
+
+*Released 2.8.3*
+
+- Moved ``Bot._requestURL`` to its own class (``telegram.utils.request``)
+- Much better, such wow, Telegram Objects tests
+- Add consistency for ``str`` properties on Telegram Objects
+- Better design to test if ``chat_id`` is invalid
+- Add ability to set custom filename on ``Bot.sendDocument(..,filename='')``
+- Fix Sticker as ``InputFile``
+- Send JSON requests over urlencoded post data
+- Markdown support for ``Bot.sendMessage(..., parse_mode=ParseMode.MARKDOWN)``
+- Refactor of ``TelegramError`` class (no more handling ``IOError`` or ``URLError``)
+
+**2015-09-05**
+
+*Released 2.8.2*
+
+- Fix regression on Telegram ReplyMarkup
+- Add certificate to ``is_inputfile`` method
+
+**2015-09-05**
+
+*Released 2.8.1*
+
+- Fix regression on Telegram objects with thumb properties
+
+**2015-09-04**
+
+*Released 2.8*
+
+- TelegramError when ``chat_id`` is empty for send* methods
+- ``setWebhook`` now supports sending self-signed certificate
+- Huge redesign of existing Telegram classes
+- Added support for PyPy
+- Added docstring for existing classes
+
+**2015-08-19**
+
+*Released 2.7.1*
+
+- Fixed JSON serialization for ``message``
+
+**2015-08-17**
+
+*Released 2.7*
+
+- Added support for ``Voice`` object and ``sendVoice`` method
+- Due backward compatibility performer or/and title will be required for ``sendAudio``
+- Fixed JSON serialization when forwarded message
+
+**2015-08-15**
+
+*Released 2.6.1*
+
+- Fixed parsing image header issue on < Python 2.7.3
+
+**2015-08-14**
+
+*Released 2.6.0*
+
+- Depreciation of ``require_authentication`` and ``clearCredentials`` methods
+- Giving ``AUTHORS`` the proper credits for their contribution for this project
+- ``Message.date`` and ``Message.forward_date`` are now ``datetime`` objects
+
+**2015-08-12**
+
+*Released 2.5.3*
+
+- ``telegram.Bot`` now supports to be unpickled
+
+**2015-08-11**
+
+*Released 2.5.2*
+
+- New changes from Telegram Bot API have been applied
+- ``telegram.Bot`` now supports to be pickled
+- Return empty ``str`` instead ``None`` when ``message.text`` is empty
+
+**2015-08-10**
+
+*Released 2.5.1*
+
+- Moved from GPLv2 to LGPLv3
+
+**2015-08-09**
+
+*Released 2.5*
+
+- Fixes logging calls in API
+
+**2015-08-08**
+
+*Released 2.4*
+
+- Fixes ``Emoji`` class for Python 3
+- ``PEP8`` improvements
+
+**2015-08-08**
+
+*Released 2.3*
+
+- Fixes ``ForceReply`` class
+- Remove ``logging.basicConfig`` from library
+
+**2015-07-25**
+
+*Released 2.2*
+
+- Allows ``debug=True`` when initializing ``telegram.Bot``
+
+**2015-07-20**
+
+*Released 2.1*
+
+- Fix ``to_dict`` for ``Document`` and ``Video``
+
+**2015-07-19**
+
+*Released 2.0*
+
+- Fixes bugs
+- Improves ``__str__`` over ``to_json()``
+- Creates abstract class ``TelegramObject``
+
+**2015-07-15**
+
+*Released 1.9*
+
+- Python 3 officially supported
+- ``PEP8`` improvements
+
+**2015-07-12**
+
+*Released 1.8*
+
+- Fixes crash when replying an unicode text message (special thanks to JRoot3D)
+
+**2015-07-11**
+
+*Released 1.7*
+
+- Fixes crash when ``username`` is not defined on ``chat`` (special thanks to JRoot3D)
+
+**2015-07-10**
+
+*Released 1.6*
+
+- Improvements for GAE support
+
+**2015-07-10**
+
+*Released 1.5*
+
+- Fixes randomly unicode issues when using ``InputFile``
+
+**2015-07-10**
+
+*Released 1.4*
+
+- ``requests`` lib is no longer required
+- Google App Engine (GAE) is supported
+
+**2015-07-10**
+
+*Released 1.3*
+
+- Added support to ``setWebhook`` (special thanks to macrojames)
+
+**2015-07-09**
+
+*Released 1.2*
+
+- ``CustomKeyboard`` classes now available
+- Emojis available
+- ``PEP8`` improvements
+
+**2015-07-08**
+
+*Released 1.1*
+
+- PyPi package now available
+
+**2015-07-08**
+
+*Released 1.0*
+
+- Initial checkin of python-telegram-bot

CODE_OF_CONDUCT.rst

@@ -0,0 +1,52 @@
+====================================
+Contributor Covenant Code of Conduct
+====================================
+
+Our Pledge
+==========
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+Our Standards
+=============
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Publication of any content supporting, justifying or otherwise affiliating with terror and/or hate towards others
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+Our Responsibilities
+====================
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+Scope
+=====
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+Enforcement
+===========
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+Attribution
+===========
+
+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/>`_.

LICENSE

@@ -0,0 +1,619 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. [http://fsf.org/]
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.

LICENSE.dual

@@ -0,0 +1,792 @@
+  NOTICE: You can find here the GPLv3 license and after the Lesser GPLv3 license.
+You may choose either license.
+
+
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. [http://fsf.org/]
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+
+
+
+
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. [http://fsf.org/]
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.

LICENSE.lesser

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. [http://fsf.org/]
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

README.md

@@ -1,20 +1,7 @@
----
-title: Santim
-emoji: 🚀
-colorFrom: blue
-colorTo: green
-sdk: docker
-pinned: false
-hf_oauth: true
-hf_oauth_expiration_minutes: 36000
-hf_oauth_scopes:
-- read-repos
-- write-repos
-- manage-repos
-- inference-api
-- read-billing
-tags:
-- autotrain
----
+# Documentation tests
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+This directory contains tests that cover our scripting logic for automatically generating
+additional elements for the documentation pages.
+
+These tests are not meant to be run with the general test suite, so the modules do not have any
+`test_` prefix in their names. By default, `pytest` ignores files that have no such prefix.

README.rst

@@ -0,0 +1,111 @@
+==============
+Testing in PTB
+==============
+
+PTB uses `pytest`_ for testing. To run the tests, you need to
+have pytest installed along with a few other dependencies. You can find the list of dependencies
+in the ``pyproject.toml`` file in the root of the repository.
+
+Running tests
+=============
+
+To run the entire test suite, you can use the following command:
+
+.. code-block:: bash
+
+    $ pytest
+
+This will run all the tests, including the ones which make a request to the Telegram servers, which
+may take a long time (total > 13 mins). To run only the tests that don't require a connection, you
+can run the following command:
+
+.. code-block:: bash
+
+    $ pytest -m no_req
+
+Or alternatively, you can run the following command to run only the tests that require a connection:
+
+.. code-block:: bash
+
+    $ pytest -m req
+
+To further speed up the tests, you can run them in parallel using the ``-n`` flag (requires `pytest-xdist`_). But beware that
+this will use multiple CPU cores on your machine. The ``--dist`` flag is used to specify how the
+tests will be distributed across the cores. The ``loadgroup`` option is used to distribute the tests
+such that tests marked with ``@pytest.mark.xdist_group("name")`` are run on the same core — important if you want avoid race conditions in some tests:
+
+.. code-block:: bash
+
+    $ pytest -n auto --dist=loadgroup
+
+This will result in a significant speedup, but may cause some tests to fail. If you want to run
+the failed tests in isolation, you can use the ``--lf`` flag:
+
+.. code-block:: bash
+
+    $ pytest --lf
+
+
+Writing tests
+=============
+
+PTB has a separate test file for every file in the ``telegram.*`` namespace. Further, the tests for
+the ``telegram`` module are split into two classes, based on whether the test methods in them make a
+request or not. When writing tests, make sure to split them into these two classes, and make sure
+to name the test class as: ``TestXXXWithoutRequest`` for tests that don't make a request, and ``TestXXXWithRequest`` for tests that do.
+
+Writing tests is a creative process; allowing you to design your test however you'd like, but there
+are a few conventions that you should follow:
+
+- Each new test class needs a ``test_slot_behaviour``, ``test_to_dict``, ``test_de_json`` and
+  ``test_equality`` (in most cases).
+
+- Make use of pytest's fixtures and parametrize wherever possible. Having knowledge of pytest's
+  tooling can help you as well. You can look at the existing tests for examples and inspiration.
+
+- New fixtures should go into ``conftest.py``. New auxiliary functions and classes, used either directly in the tests or in the fixtures, should go into the ``tests/auxil`` directory.
+
+If you have made some API changes, you may want to run ``test_official`` to validate that the changes are
+complete and correct. To run it, export an environment variable first:
+
+.. code-block:: bash
+
+    $ export TEST_OFFICIAL=true
+
+and then run ``pytest tests/test_official.py``. Note: You need py 3.10+ to run this test.
+
+We also have another marker, ``@pytest.mark.dev``, which you can add to tests that you want to run selectively.
+Use as follows:
+
+.. code-block:: bash
+
+    $ pytest -m dev
+
+
+Debugging tests
+===============
+
+Writing tests can be challenging, and fixing failing tests can be even more so. To help with this,
+PTB has started to adopt the use of ``logging`` in the test suite. You can insert debug logging 
+statements in your tests to help you understand what's going on. To enable these logs, you can set 
+``log_level = DEBUG`` in ``setup.cfg`` or use the ``--log-level=INFO`` flag when running the tests.
+If a test is large and complicated, it is recommended to leave the debug logs for others to use as 
+well.
+
+
+Bots used in tests
+==================
+
+If you run the tests locally, the test setup will use one of the two public bots available. Which
+bot of the two gets chosen for the test session is random. Whereas when the tests on the
+Github Actions CI are run, the test setup allocates a different, but same bot is for every combination of Python version and
+OS. The operating systems and Python versions the CI runs the tests on can be viewed in the `corresponding workflow`_.
+
+
+That's it! If you have any questions, feel free to ask them in the `PTB dev
+group`_.
+
+.. _pytest: https://docs.pytest.org/en/stable/
+.. _pytest-xdist: https://pypi.org/project/pytest-xdist/
+.. _PTB dev group: https://t.me/pythontelegrambotgroup
+.. _corresponding workflow: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/workflows/unit_tests.yml

__main__.py

@@ -0,0 +1,54 @@
+# !/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=missing-module-docstring
+# ruff: noqa: T201, D100, S603, S607
+import subprocess
+import sys
+from typing import Optional
+
+from . import __version__ as telegram_ver
+from .constants import BOT_API_VERSION
+
+
+def _git_revision() -> Optional[str]:
+    try:
+        output = subprocess.check_output(
+            ["git", "describe", "--long", "--tags"], stderr=subprocess.STDOUT
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    return output.decode().strip()
+
+
+def print_ver_info() -> None:
+    """Prints version information for python-telegram-bot, the Bot API and Python."""
+    git_revision = _git_revision()
+    print(f"python-telegram-bot {telegram_ver}" + (f" ({git_revision})" if git_revision else ""))
+    print(f"Bot API {BOT_API_VERSION}")
+    sys_version = sys.version.replace("\n", " ")
+    print(f"Python {sys_version}")
+
+
+def main() -> None:
+    """Prints version information for python-telegram-bot, the Bot API and Python."""
+    print_ver_info()
+
+
+if __name__ == "__main__":
+    main()

_birthdate.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram Birthday."""
+from datetime import date
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class Birthdate(TelegramObject):
+    """
+    This object describes the birthdate of a user.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`day`, and :attr:`month` are equal.
+
+    .. versionadded:: 21.1
+
+    Args:
+        day (:obj:`int`): Day of the user's birth; 1-31.
+        month (:obj:`int`): Month of the user's birth; 1-12.
+        year (:obj:`int`, optional): Year of the user's birth.
+
+    Attributes:
+        day (:obj:`int`): Day of the user's birth; 1-31.
+        month (:obj:`int`): Month of the user's birth; 1-12.
+        year (:obj:`int`): Optional. Year of the user's birth.
+
+    """
+
+    __slots__ = ("day", "month", "year")
+
+    def __init__(
+        self,
+        day: int,
+        month: int,
+        year: Optional[int] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        # Required
+        self.day: int = day
+        self.month: int = month
+        # Optional
+        self.year: Optional[int] = year
+
+        self._id_attrs = (
+            self.day,
+            self.month,
+        )
+
+        self._freeze()
+
+    def to_date(self, year: Optional[int] = None) -> date:
+        """Return the birthdate as a date object.
+
+        .. versionchanged:: 21.2
+           Now returns a :obj:`datetime.date` object instead of a :obj:`datetime.datetime` object,
+           as was originally intended.
+
+        Args:
+            year (:obj:`int`, optional): The year to use. Required, if the :attr:`year` was not
+                present.
+
+        Returns:
+            :obj:`datetime.date`: The birthdate as a date object.
+        """
+        if self.year is None and year is None:
+            raise ValueError(
+                "The `year` argument is required if the `year` attribute was not present."
+            )
+
+        return date(year or self.year, self.month, self.day)  # type: ignore[arg-type]

_botcommand.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram Bot Command."""
+
+from typing import Final, Optional
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class BotCommand(TelegramObject):
+    """
+    This object represents a bot command.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`command` and :attr:`description` are equal.
+
+    Args:
+        command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`-
+            :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase
+            English letters, digits and underscores.
+        description (:obj:`str`): Description of the command;
+            :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`-
+            :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters.
+
+    Attributes:
+        command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`-
+            :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase
+            English letters, digits and underscores.
+        description (:obj:`str`): Description of the command;
+            :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`-
+            :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters.
+
+    """
+
+    __slots__ = ("command", "description")
+
+    def __init__(self, command: str, description: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.command: str = command
+        self.description: str = description
+
+        self._id_attrs = (self.command, self.description)
+
+        self._freeze()
+
+    MIN_COMMAND: Final[int] = constants.BotCommandLimit.MIN_COMMAND
+    """:const:`telegram.constants.BotCommandLimit.MIN_COMMAND`
+
+    .. versionadded:: 20.0
+    """
+    MAX_COMMAND: Final[int] = constants.BotCommandLimit.MAX_COMMAND
+    """:const:`telegram.constants.BotCommandLimit.MAX_COMMAND`
+
+    .. versionadded:: 20.0
+    """
+    MIN_DESCRIPTION: Final[int] = constants.BotCommandLimit.MIN_DESCRIPTION
+    """:const:`telegram.constants.BotCommandLimit.MIN_DESCRIPTION`
+
+    .. versionadded:: 20.0
+    """
+    MAX_DESCRIPTION: Final[int] = constants.BotCommandLimit.MAX_DESCRIPTION
+    """:const:`telegram.constants.BotCommandLimit.MAX_DESCRIPTION`
+
+    .. versionadded:: 20.0
+    """

_botcommandscope.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=redefined-builtin
+"""This module contains objects representing Telegram bot command scopes."""
+from typing import TYPE_CHECKING, Dict, Final, Optional, Type, Union
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._utils import enum
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class BotCommandScope(TelegramObject):
+    """Base class for objects that represent the scope to which bot commands are applied.
+    Currently, the following 7 scopes are supported:
+
+    * :class:`telegram.BotCommandScopeDefault`
+    * :class:`telegram.BotCommandScopeAllPrivateChats`
+    * :class:`telegram.BotCommandScopeAllGroupChats`
+    * :class:`telegram.BotCommandScopeAllChatAdministrators`
+    * :class:`telegram.BotCommandScopeChat`
+    * :class:`telegram.BotCommandScopeChatAdministrators`
+    * :class:`telegram.BotCommandScopeChatMember`
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal. For subclasses with additional attributes,
+    the notion of equality is overridden.
+
+    Note:
+        Please see the `official docs`_ on how Telegram determines which commands to display.
+
+    .. _`official docs`: https://core.telegram.org/bots/api#determining-list-of-commands
+
+    .. versionadded:: 13.7
+
+    Args:
+        type (:obj:`str`): Scope type.
+
+    Attributes:
+        type (:obj:`str`): Scope type.
+    """
+
+    __slots__ = ("type",)
+
+    DEFAULT: Final[str] = constants.BotCommandScopeType.DEFAULT
+    """:const:`telegram.constants.BotCommandScopeType.DEFAULT`"""
+    ALL_PRIVATE_CHATS: Final[str] = constants.BotCommandScopeType.ALL_PRIVATE_CHATS
+    """:const:`telegram.constants.BotCommandScopeType.ALL_PRIVATE_CHATS`"""
+    ALL_GROUP_CHATS: Final[str] = constants.BotCommandScopeType.ALL_GROUP_CHATS
+    """:const:`telegram.constants.BotCommandScopeType.ALL_GROUP_CHATS`"""
+    ALL_CHAT_ADMINISTRATORS: Final[str] = constants.BotCommandScopeType.ALL_CHAT_ADMINISTRATORS
+    """:const:`telegram.constants.BotCommandScopeType.ALL_CHAT_ADMINISTRATORS`"""
+    CHAT: Final[str] = constants.BotCommandScopeType.CHAT
+    """:const:`telegram.constants.BotCommandScopeType.CHAT`"""
+    CHAT_ADMINISTRATORS: Final[str] = constants.BotCommandScopeType.CHAT_ADMINISTRATORS
+    """:const:`telegram.constants.BotCommandScopeType.CHAT_ADMINISTRATORS`"""
+    CHAT_MEMBER: Final[str] = constants.BotCommandScopeType.CHAT_MEMBER
+    """:const:`telegram.constants.BotCommandScopeType.CHAT_MEMBER`"""
+
+    def __init__(self, type: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.type: str = enum.get_member(constants.BotCommandScopeType, type, type)
+        self._id_attrs = (self.type,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BotCommandScope"]:
+        """Converts JSON data to the appropriate :class:`BotCommandScope` object, i.e. takes
+        care of selecting the correct subclass.
+
+        Args:
+            data (Dict[:obj:`str`, ...]): The JSON data.
+            bot (:class:`telegram.Bot`, optional): The bot associated with this object. Defaults to
+                :obj:`None`, in which case shortcut methods will not be available.
+
+                .. versionchanged:: 21.4
+                   :paramref:`bot` is now optional and defaults to :obj:`None`
+
+        Returns:
+            The Telegram object.
+
+        """
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[BotCommandScope]] = {
+            cls.DEFAULT: BotCommandScopeDefault,
+            cls.ALL_PRIVATE_CHATS: BotCommandScopeAllPrivateChats,
+            cls.ALL_GROUP_CHATS: BotCommandScopeAllGroupChats,
+            cls.ALL_CHAT_ADMINISTRATORS: BotCommandScopeAllChatAdministrators,
+            cls.CHAT: BotCommandScopeChat,
+            cls.CHAT_ADMINISTRATORS: BotCommandScopeChatAdministrators,
+            cls.CHAT_MEMBER: BotCommandScopeChatMember,
+        }
+
+        if cls is BotCommandScope and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+        return super().de_json(data=data, bot=bot)
+
+
+class BotCommandScopeDefault(BotCommandScope):
+    """Represents the default scope of bot commands. Default commands are used if no commands with
+    a `narrower scope`_ are specified for the user.
+
+    .. _`narrower scope`: https://core.telegram.org/bots/api#determining-list-of-commands
+
+    .. versionadded:: 13.7
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.DEFAULT`.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=BotCommandScope.DEFAULT, api_kwargs=api_kwargs)
+        self._freeze()
+
+
+class BotCommandScopeAllPrivateChats(BotCommandScope):
+    """Represents the scope of bot commands, covering all private chats.
+
+    .. versionadded:: 13.7
+
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.ALL_PRIVATE_CHATS`.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=BotCommandScope.ALL_PRIVATE_CHATS, api_kwargs=api_kwargs)
+        self._freeze()
+
+
+class BotCommandScopeAllGroupChats(BotCommandScope):
+    """Represents the scope of bot commands, covering all group and supergroup chats.
+
+    .. versionadded:: 13.7
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.ALL_GROUP_CHATS`.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=BotCommandScope.ALL_GROUP_CHATS, api_kwargs=api_kwargs)
+        self._freeze()
+
+
+class BotCommandScopeAllChatAdministrators(BotCommandScope):
+    """Represents the scope of bot commands, covering all group and supergroup chat administrators.
+
+    .. versionadded:: 13.7
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.ALL_CHAT_ADMINISTRATORS`.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=BotCommandScope.ALL_CHAT_ADMINISTRATORS, api_kwargs=api_kwargs)
+        self._freeze()
+
+
+class BotCommandScopeChat(BotCommandScope):
+    """Represents the scope of bot commands, covering a specific chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` and :attr:`chat_id` are equal.
+
+    .. versionadded:: 13.7
+
+    Args:
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
+
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT`.
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
+    """
+
+    __slots__ = ("chat_id",)
+
+    def __init__(self, chat_id: Union[str, int], *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=BotCommandScope.CHAT, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.chat_id: Union[str, int] = (
+                chat_id if isinstance(chat_id, str) and chat_id.startswith("@") else int(chat_id)
+            )
+            self._id_attrs = (self.type, self.chat_id)
+
+
+class BotCommandScopeChatAdministrators(BotCommandScope):
+    """Represents the scope of bot commands, covering all administrators of a specific group or
+    supergroup chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` and :attr:`chat_id` are equal.
+
+    .. versionadded:: 13.7
+
+    Args:
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_ADMINISTRATORS`.
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
+    """
+
+    __slots__ = ("chat_id",)
+
+    def __init__(self, chat_id: Union[str, int], *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=BotCommandScope.CHAT_ADMINISTRATORS, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.chat_id: Union[str, int] = (
+                chat_id if isinstance(chat_id, str) and chat_id.startswith("@") else int(chat_id)
+            )
+            self._id_attrs = (self.type, self.chat_id)
+
+
+class BotCommandScopeChatMember(BotCommandScope):
+    """Represents the scope of bot commands, covering a specific member of a group or supergroup
+    chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type`, :attr:`chat_id` and :attr:`user_id` are equal.
+
+    .. versionadded:: 13.7
+
+    Args:
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
+        user_id (:obj:`int`): Unique identifier of the target user.
+
+    Attributes:
+        type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_MEMBER`.
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
+        user_id (:obj:`int`): Unique identifier of the target user.
+    """
+
+    __slots__ = ("chat_id", "user_id")
+
+    def __init__(
+        self, chat_id: Union[str, int], user_id: int, *, api_kwargs: Optional[JSONDict] = None
+    ):
+        super().__init__(type=BotCommandScope.CHAT_MEMBER, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.chat_id: Union[str, int] = (
+                chat_id if isinstance(chat_id, str) and chat_id.startswith("@") else int(chat_id)
+            )
+            self.user_id: int = user_id
+            self._id_attrs = (self.type, self.chat_id, self.user_id)

_botdescription.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains two objects that represent a Telegram bots (short) description."""
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class BotDescription(TelegramObject):
+    """This object represents the bot's description.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`description` is equal.
+
+    .. versionadded:: 20.2
+
+    Args:
+        description (:obj:`str`): The bot's description.
+
+    Attributes:
+        description (:obj:`str`): The bot's description.
+
+    """
+
+    __slots__ = ("description",)
+
+    def __init__(self, description: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.description: str = description
+
+        self._id_attrs = (self.description,)
+
+        self._freeze()
+
+
+class BotShortDescription(TelegramObject):
+    """This object represents the bot's short description.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`short_description` is equal.
+
+    .. versionadded:: 20.2
+
+    Args:
+        short_description (:obj:`str`): The bot's short description.
+
+    Attributes:
+        short_description (:obj:`str`): The bot's short description.
+
+    """
+
+    __slots__ = ("short_description",)
+
+    def __init__(self, short_description: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.short_description: str = short_description
+
+        self._id_attrs = (self.short_description,)
+
+        self._freeze()

_botname.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represent a Telegram bots name."""
+from typing import Final, Optional
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class BotName(TelegramObject):
+    """This object represents the bot's name.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`name` is equal.
+
+    .. versionadded:: 20.3
+
+    Args:
+        name (:obj:`str`): The bot's name.
+
+    Attributes:
+        name (:obj:`str`): The bot's name.
+
+    """
+
+    __slots__ = ("name",)
+
+    def __init__(self, name: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.name: str = name
+
+        self._id_attrs = (self.name,)
+
+        self._freeze()
+
+    MAX_LENGTH: Final[int] = constants.BotNameLimit.MAX_NAME_LENGTH
+    """:const:`telegram.constants.BotNameLimit.MAX_NAME_LENGTH`"""

_business.py

@@ -0,0 +1,455 @@
+#!/usr/bin/env python
+# pylint: disable=redefined-builtin
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/]
+"""This module contains the Telegram Business related classes."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+
+from telegram._chat import Chat
+from telegram._files.location import Location
+from telegram._files.sticker import Sticker
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class BusinessConnection(TelegramObject):
+    """
+    Describes the connection of the bot with a business account.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal if their :attr:`id`, :attr:`user`, :attr:`user_chat_id`, :attr:`date`,
+    :attr:`can_reply`, and :attr:`is_enabled` are equal.
+
+    .. versionadded:: 21.1
+
+    Args:
+        id (:obj:`str`): Unique identifier of the business connection.
+        user (:class:`telegram.User`): Business account user that created the business connection.
+        user_chat_id (:obj:`int`): Identifier of a private chat with the user who created the
+            business connection.
+        date (:obj:`datetime.datetime`): Date the connection was established in Unix time.
+        can_reply (:obj:`bool`): True, if the bot can act on behalf of the business account in
+            chats that were active in the last 24 hours.
+        is_enabled (:obj:`bool`): True, if the connection is active.
+
+    Attributes:
+        id (:obj:`str`): Unique identifier of the business connection.
+        user (:class:`telegram.User`): Business account user that created the business connection.
+        user_chat_id (:obj:`int`): Identifier of a private chat with the user who created the
+            business connection.
+        date (:obj:`datetime.datetime`): Date the connection was established in Unix time.
+        can_reply (:obj:`bool`): True, if the bot can act on behalf of the business account in
+            chats that were active in the last 24 hours.
+        is_enabled (:obj:`bool`): True, if the connection is active.
+    """
+
+    __slots__ = (
+        "can_reply",
+        "date",
+        "id",
+        "is_enabled",
+        "user",
+        "user_chat_id",
+    )
+
+    def __init__(
+        self,
+        id: str,
+        user: "User",
+        user_chat_id: int,
+        date: datetime,
+        can_reply: bool,
+        is_enabled: bool,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.id: str = id
+        self.user: User = user
+        self.user_chat_id: int = user_chat_id
+        self.date: datetime = date
+        self.can_reply: bool = can_reply
+        self.is_enabled: bool = is_enabled
+
+        self._id_attrs = (
+            self.id,
+            self.user,
+            self.user_chat_id,
+            self.date,
+            self.can_reply,
+            self.is_enabled,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessConnection"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
+        data["user"] = User.de_json(data.get("user"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BusinessMessagesDeleted(TelegramObject):
+    """
+    This object is received when messages are deleted from a connected business account.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal if their :attr:`business_connection_id`, :attr:`message_ids`, and
+    :attr:`chat` are equal.
+
+    .. versionadded:: 21.1
+
+    Args:
+        business_connection_id (:obj:`str`): Unique identifier of the business connection.
+        chat (:class:`telegram.Chat`): Information about a chat in the business account. The bot
+            may not have access to the chat or the corresponding user.
+        message_ids (Sequence[:obj:`int`]): A list of identifiers of the deleted messages in the
+            chat of the business account.
+
+    Attributes:
+        business_connection_id (:obj:`str`): Unique identifier of the business connection.
+        chat (:class:`telegram.Chat`): Information about a chat in the business account. The bot
+            may not have access to the chat or the corresponding user.
+        message_ids (Tuple[:obj:`int`]): A list of identifiers of the deleted messages in the
+            chat of the business account.
+    """
+
+    __slots__ = (
+        "business_connection_id",
+        "chat",
+        "message_ids",
+    )
+
+    def __init__(
+        self,
+        business_connection_id: str,
+        chat: Chat,
+        message_ids: Sequence[int],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.business_connection_id: str = business_connection_id
+        self.chat: Chat = chat
+        self.message_ids: Tuple[int, ...] = parse_sequence_arg(message_ids)
+
+        self._id_attrs = (
+            self.business_connection_id,
+            self.chat,
+            self.message_ids,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessMessagesDeleted"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BusinessIntro(TelegramObject):
+    """
+    This object contains information about the start page settings of a Telegram Business account.
+
+    Objects of this class are comparable in terms of equality.
+    Two objects of this class are considered equal, if their
+    :attr:`title`, :attr:`message` and :attr:`sticker` are equal.
+
+    .. versionadded:: 21.1
+
+    Args:
+        title (:obj:`str`, optional): Title text of the business intro.
+        message (:obj:`str`, optional): Message text of the business intro.
+        sticker (:class:`telegram.Sticker`, optional): Sticker of the business intro.
+
+    Attributes:
+        title (:obj:`str`): Optional. Title text of the business intro.
+        message (:obj:`str`): Optional. Message text of the business intro.
+        sticker (:class:`telegram.Sticker`): Optional. Sticker of the business intro.
+    """
+
+    __slots__ = (
+        "message",
+        "sticker",
+        "title",
+    )
+
+    def __init__(
+        self,
+        title: Optional[str] = None,
+        message: Optional[str] = None,
+        sticker: Optional[Sticker] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.title: Optional[str] = title
+        self.message: Optional[str] = message
+        self.sticker: Optional[Sticker] = sticker
+
+        self._id_attrs = (self.title, self.message, self.sticker)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessIntro"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["sticker"] = Sticker.de_json(data.get("sticker"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BusinessLocation(TelegramObject):
+    """
+    This object contains information about the location of a Telegram Business account.
+
+    Objects of this class are comparable in terms of equality.
+    Two objects of this class are considered equal, if their
+    :attr:`address` is equal.
+
+    .. versionadded:: 21.1
+
+    Args:
+        address (:obj:`str`): Address of the business.
+        location (:class:`telegram.Location`, optional): Location of the business.
+
+    Attributes:
+        address (:obj:`str`): Address of the business.
+        location (:class:`telegram.Location`): Optional. Location of the business.
+    """
+
+    __slots__ = (
+        "address",
+        "location",
+    )
+
+    def __init__(
+        self,
+        address: str,
+        location: Optional[Location] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.address: str = address
+        self.location: Optional[Location] = location
+
+        self._id_attrs = (self.address,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessLocation"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["location"] = Location.de_json(data.get("location"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BusinessOpeningHoursInterval(TelegramObject):
+    """
+    This object describes an interval of time during which a business is open.
+
+    Objects of this class are comparable in terms of equality.
+    Two objects of this class are considered equal, if their
+    :attr:`opening_minute` and :attr:`closing_minute` are equal.
+
+    .. versionadded:: 21.1
+
+    Examples:
+        A day has (24 * 60 =) 1440 minutes, a week has (7 * 1440 =) 10080 minutes.
+        Starting the the minute's sequence from Monday, example values of
+        :attr:`opening_minute`, :attr:`closing_minute` will map to the following day times:
+
+        * Monday - 8am to 8:30pm:
+            - ``opening_minute = 480`` :guilabel:`8 * 60`
+            - ``closing_minute = 1230`` :guilabel:`20 * 60 + 30`
+        * Tuesday - 24 hours:
+            - ``opening_minute = 1440`` :guilabel:`24 * 60`
+            - ``closing_minute = 2879`` :guilabel:`2 * 24 * 60 - 1`
+        * Sunday - 12am - 11:58pm:
+            - ``opening_minute = 8640`` :guilabel:`6 * 24 * 60`
+            - ``closing_minute = 10078`` :guilabel:`7 * 24 * 60 - 2`
+
+    Args:
+        opening_minute (:obj:`int`): The minute's sequence number in a week, starting on Monday,
+            marking the start of the time interval during which the business is open;
+            0 - 7 * 24 * 60.
+        closing_minute (:obj:`int`): The minute's
+            sequence number in a week, starting on Monday, marking the end of the time interval
+            during which the business is open; 0 - 8 * 24 * 60
+
+    Attributes:
+        opening_minute (:obj:`int`): The minute's sequence number in a week, starting on Monday,
+            marking the start of the time interval during which the business is open;
+            0 - 7 * 24 * 60.
+        closing_minute (:obj:`int`): The minute's
+            sequence number in a week, starting on Monday, marking the end of the time interval
+            during which the business is open; 0 - 8 * 24 * 60
+    """
+
+    __slots__ = ("_closing_time", "_opening_time", "closing_minute", "opening_minute")
+
+    def __init__(
+        self,
+        opening_minute: int,
+        closing_minute: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.opening_minute: int = opening_minute
+        self.closing_minute: int = closing_minute
+
+        self._opening_time: Optional[Tuple[int, int, int]] = None
+        self._closing_time: Optional[Tuple[int, int, int]] = None
+
+        self._id_attrs = (self.opening_minute, self.closing_minute)
+
+        self._freeze()
+
+    def _parse_minute(self, minute: int) -> Tuple[int, int, int]:
+        return (minute // 1440, minute % 1440 // 60, minute % 1440 % 60)
+
+    @property
+    def opening_time(self) -> Tuple[int, int, int]:
+        """Convenience attribute. A :obj:`tuple` parsed from :attr:`opening_minute`. It contains
+        the `weekday`, `hour` and `minute` in the same ranges as :attr:`datetime.datetime.weekday`,
+        :attr:`datetime.datetime.hour` and :attr:`datetime.datetime.minute`
+
+        Returns:
+            Tuple[:obj:`int`, :obj:`int`, :obj:`int`]:
+        """
+        if self._opening_time is None:
+            self._opening_time = self._parse_minute(self.opening_minute)
+        return self._opening_time
+
+    @property
+    def closing_time(self) -> Tuple[int, int, int]:
+        """Convenience attribute. A :obj:`tuple` parsed from :attr:`closing_minute`. It contains
+        the `weekday`, `hour` and `minute` in the same ranges as :attr:`datetime.datetime.weekday`,
+        :attr:`datetime.datetime.hour` and :attr:`datetime.datetime.minute`
+
+        Returns:
+            Tuple[:obj:`int`, :obj:`int`, :obj:`int`]:
+        """
+        if self._closing_time is None:
+            self._closing_time = self._parse_minute(self.closing_minute)
+        return self._closing_time
+
+
+class BusinessOpeningHours(TelegramObject):
+    """
+    This object describes the opening hours of a business.
+
+    Objects of this class are comparable in terms of equality.
+    Two objects of this class are considered equal, if their
+    :attr:`time_zone_name` and :attr:`opening_hours` are equal.
+
+    .. versionadded:: 21.1
+
+    Args:
+        time_zone_name (:obj:`str`): Unique name of the time zone for which the opening
+            hours are defined.
+        opening_hours (Sequence[:class:`telegram.BusinessOpeningHoursInterval`]): List of
+            time intervals describing business opening hours.
+
+    Attributes:
+        time_zone_name (:obj:`str`): Unique name of the time zone for which the opening
+            hours are defined.
+        opening_hours (Sequence[:class:`telegram.BusinessOpeningHoursInterval`]): List of
+            time intervals describing business opening hours.
+    """
+
+    __slots__ = ("opening_hours", "time_zone_name")
+
+    def __init__(
+        self,
+        time_zone_name: str,
+        opening_hours: Sequence[BusinessOpeningHoursInterval],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.time_zone_name: str = time_zone_name
+        self.opening_hours: Sequence[BusinessOpeningHoursInterval] = parse_sequence_arg(
+            opening_hours
+        )
+
+        self._id_attrs = (self.time_zone_name, self.opening_hours)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BusinessOpeningHours"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["opening_hours"] = BusinessOpeningHoursInterval.de_list(
+            data.get("opening_hours"), bot
+        )
+
+        return super().de_json(data=data, bot=bot)

_callbackquery.py

@@ -0,0 +1,892 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=redefined-builtin
+"""This module contains an object that represents a Telegram CallbackQuery"""
+from typing import TYPE_CHECKING, Final, Optional, Sequence, Tuple, Union
+
+from telegram import constants
+from telegram._files.location import Location
+from telegram._message import MaybeInaccessibleMessage, Message
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.defaultvalue import DEFAULT_NONE
+from telegram._utils.types import JSONDict, ODVInput, ReplyMarkup
+
+if TYPE_CHECKING:
+    from telegram import (
+        Bot,
+        GameHighScore,
+        InlineKeyboardMarkup,
+        InputMedia,
+        LinkPreviewOptions,
+        MessageEntity,
+        MessageId,
+        ReplyParameters,
+    )
+
+
+class CallbackQuery(TelegramObject):
+    """
+    This object represents an incoming callback query from a callback button in an inline keyboard.
+
+    If the button that originated the query was attached to a message sent by the bot, the field
+    :attr:`message` will be present. If the button was attached to a message sent via the bot (in
+    inline mode), the field :attr:`inline_message_id` will be present.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`id` is equal.
+
+    Note:
+        * In Python :keyword:`from` is a reserved word. Use :paramref:`from_user` instead.
+        * Exactly one of the fields :attr:`data` or :attr:`game_short_name` will be present.
+        * After the user presses an inline button, Telegram clients will display a progress bar
+          until you call :attr:`answer`. It is, therefore, necessary to react
+          by calling :attr:`telegram.Bot.answer_callback_query` even if no notification to the user
+          is needed (e.g., without specifying any of the optional parameters).
+        * If you're using :attr:`telegram.ext.ExtBot.callback_data_cache`, :attr:`data` may be
+          an instance
+          of :class:`telegram.ext.InvalidCallbackData`. This will be the case, if the data
+          associated with the button triggering the :class:`telegram.CallbackQuery` was already
+          deleted or if :attr:`data` was manipulated by a malicious client.
+
+          .. versionadded:: 13.6
+
+    Args:
+        id (:obj:`str`): Unique identifier for this query.
+        from_user (:class:`telegram.User`): Sender.
+        chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which
+            the message with the callback button was sent. Useful for high scores in games.
+        message (:class:`telegram.MaybeInaccessibleMessage`, optional): Message sent by the bot
+            with the callback button that originated the query.
+
+            .. versionchanged:: 20.8
+               Accept objects of type :class:`telegram.MaybeInaccessibleMessage` since Bot API 7.0.
+        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
+            the unique identifier for the game.
+
+    Attributes:
+        id (:obj:`str`): Unique identifier for this query.
+        from_user (:class:`telegram.User`): Sender.
+        chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which
+            the message with the callback button was sent. Useful for high scores in games.
+        message (:class:`telegram.MaybeInaccessibleMessage`): Optional. Message sent by the bot
+            with the callback button that originated the query.
+
+            .. versionchanged:: 20.8
+               Objects may be of type :class:`telegram.MaybeInaccessibleMessage` since Bot API
+               7.0.
+        data (:obj:`str` | :obj:`object`): Optional. Data associated with the callback button.
+            Be aware that the message, which originated the query, can contain no callback buttons
+            with this data.
+
+            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, serves as
+            the unique identifier for the game.
+
+
+    """
+
+    __slots__ = (
+        "chat_instance",
+        "data",
+        "from_user",
+        "game_short_name",
+        "id",
+        "inline_message_id",
+        "message",
+    )
+
+    def __init__(
+        self,
+        id: str,
+        from_user: User,
+        chat_instance: str,
+        message: Optional[MaybeInaccessibleMessage] = None,
+        data: Optional[str] = None,
+        inline_message_id: Optional[str] = None,
+        game_short_name: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.id: str = id
+        self.from_user: User = from_user
+        self.chat_instance: str = chat_instance
+        # Optionals
+        self.message: Optional[MaybeInaccessibleMessage] = message
+        self.data: Optional[str] = data
+        self.inline_message_id: Optional[str] = inline_message_id
+        self.game_short_name: Optional[str] = game_short_name
+
+        self._id_attrs = (self.id,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["CallbackQuery"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        data["message"] = Message.de_json(data.get("message"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+    async def answer(
+        self,
+        text: Optional[str] = None,
+        show_alert: Optional[bool] = None,
+        url: Optional[str] = None,
+        cache_time: Optional[int] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.answer_callback_query(update.callback_query.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.answer_callback_query`.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        """
+        return await self.get_bot().answer_callback_query(
+            callback_query_id=self.id,
+            text=text,
+            show_alert=show_alert,
+            url=url,
+            cache_time=cache_time,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    def _get_message(self, action: str = "edit") -> Message:
+        """Helper method to get the message for the shortcut methods. Must be called only
+        if :attr:`inline_message_id` is *not* set.
+        """
+        if not isinstance(self.message, Message):
+            raise TypeError(f"Cannot {action} an inaccessible message")
+        return self.message
+
+    async def edit_message_text(
+        self,
+        text: str,
+        parse_mode: ODVInput[str] = DEFAULT_NONE,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        entities: Optional[Sequence["MessageEntity"]] = None,
+        link_preview_options: ODVInput["LinkPreviewOptions"] = DEFAULT_NONE,
+        *,
+        disable_web_page_preview: Optional[bool] = None,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+            await update.callback_query.message.edit_text(*args, **kwargs)
+
+        or::
+
+            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`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is sent by the bot, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().edit_message_text(
+                inline_message_id=self.inline_message_id,
+                text=text,
+                parse_mode=parse_mode,
+                disable_web_page_preview=disable_web_page_preview,
+                link_preview_options=link_preview_options,
+                reply_markup=reply_markup,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                entities=entities,
+                chat_id=None,
+                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
+            )
+        return await self._get_message().edit_text(
+            text=text,
+            parse_mode=parse_mode,
+            disable_web_page_preview=disable_web_page_preview,
+            link_preview_options=link_preview_options,
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+            entities=entities,
+        )
+
+    async def edit_message_caption(
+        self,
+        caption: Optional[str] = None,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        parse_mode: ODVInput[str] = DEFAULT_NONE,
+        caption_entities: Optional[Sequence["MessageEntity"]] = None,
+        show_caption_above_media: Optional[bool] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+            await update.callback_query.message.edit_caption(*args, **kwargs)
+
+        or::
+
+            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`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is sent by the bot, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().edit_message_caption(
+                caption=caption,
+                inline_message_id=self.inline_message_id,
+                reply_markup=reply_markup,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                parse_mode=parse_mode,
+                api_kwargs=api_kwargs,
+                caption_entities=caption_entities,
+                chat_id=None,
+                message_id=None,
+                show_caption_above_media=show_caption_above_media,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
+            )
+        return await self._get_message().edit_caption(
+            caption=caption,
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            parse_mode=parse_mode,
+            api_kwargs=api_kwargs,
+            caption_entities=caption_entities,
+            show_caption_above_media=show_caption_above_media,
+        )
+
+    async def edit_message_reply_markup(
+        self,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+            await update.callback_query.message.edit_reply_markup(*args, **kwargs)
+
+        or::
+
+            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
+        :meth:`telegram.Bot.edit_message_reply_markup` and
+        :meth:`telegram.Message.edit_reply_markup`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is sent by the bot, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().edit_message_reply_markup(
+                reply_markup=reply_markup,
+                inline_message_id=self.inline_message_id,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
+            )
+        return await self._get_message().edit_reply_markup(
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def edit_message_media(
+        self,
+        media: "InputMedia",
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+            await update.callback_query.message.edit_media(*args, **kwargs)
+
+        or::
+
+            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`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is not an inline message, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().edit_message_media(
+                inline_message_id=self.inline_message_id,
+                media=media,
+                reply_markup=reply_markup,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
+            )
+        return await self._get_message().edit_media(
+            media=media,
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def edit_message_live_location(
+        self,
+        latitude: Optional[float] = None,
+        longitude: Optional[float] = None,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        horizontal_accuracy: Optional[float] = None,
+        heading: Optional[int] = None,
+        proximity_alert_radius: Optional[int] = None,
+        live_period: Optional[int] = None,
+        *,
+        location: Optional[Location] = None,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+            await update.callback_query.message.edit_live_location(*args, **kwargs)
+
+        or::
+
+            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
+        :meth:`telegram.Bot.edit_message_live_location` and
+        :meth:`telegram.Message.edit_live_location`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is sent by the bot, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().edit_message_live_location(
+                inline_message_id=self.inline_message_id,
+                latitude=latitude,
+                longitude=longitude,
+                location=location,
+                reply_markup=reply_markup,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                horizontal_accuracy=horizontal_accuracy,
+                heading=heading,
+                proximity_alert_radius=proximity_alert_radius,
+                live_period=live_period,
+                chat_id=None,
+                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
+            )
+        return await self._get_message().edit_live_location(
+            latitude=latitude,
+            longitude=longitude,
+            location=location,
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+            horizontal_accuracy=horizontal_accuracy,
+            heading=heading,
+            proximity_alert_radius=proximity_alert_radius,
+            live_period=live_period,
+        )
+
+    async def stop_message_live_location(
+        self,
+        reply_markup: Optional["InlineKeyboardMarkup"] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+            await update.callback_query.message.stop_live_location(*args, **kwargs)
+
+        or::
+
+            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
+        :meth:`telegram.Bot.stop_message_live_location` and
+        :meth:`telegram.Message.stop_live_location`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is sent by the bot, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().stop_message_live_location(
+                inline_message_id=self.inline_message_id,
+                reply_markup=reply_markup,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+                # inline messages can not be sent on behalf of a bcid
+                business_connection_id=None,
+            )
+        return await self._get_message().stop_live_location(
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def set_game_score(
+        self,
+        user_id: int,
+        score: int,
+        force: Optional[bool] = None,
+        disable_edit_message: Optional[bool] = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Union[Message, bool]:
+        """Shortcut for either::
+
+           await update.callback_query.message.set_game_score(*args, **kwargs)
+
+        or::
+
+            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`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.Message`: On success, if edited message is sent by the bot, the
+            edited Message is returned, otherwise :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().set_game_score(
+                inline_message_id=self.inline_message_id,
+                user_id=user_id,
+                score=score,
+                force=force,
+                disable_edit_message=disable_edit_message,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return await self._get_message().set_game_score(
+            user_id=user_id,
+            score=score,
+            force=force,
+            disable_edit_message=disable_edit_message,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def get_game_high_scores(
+        self,
+        user_id: int,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> Tuple["GameHighScore", ...]:
+        """Shortcut for either::
+
+            await update.callback_query.message.get_game_high_score(*args, **kwargs)
+
+        or::
+
+            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
+        :meth:`telegram.Message.get_game_high_scores`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            Tuple[:class:`telegram.GameHighScore`]
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        if self.inline_message_id:
+            return await self.get_bot().get_game_high_scores(
+                inline_message_id=self.inline_message_id,
+                user_id=user_id,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return await self._get_message().get_game_high_scores(
+            user_id=user_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def delete_message(
+        self,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+            await update.callback_query.message.delete(*args, **kwargs)
+
+        For the documentation of the arguments, please see :meth:`telegram.Message.delete`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+
+        """
+        return await self._get_message(action="delete").delete(
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def pin_message(
+        self,
+        disable_notification: ODVInput[bool] = DEFAULT_NONE,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+            await update.callback_query.message.pin(*args, **kwargs)
+
+        For the documentation of the arguments, please see :meth:`telegram.Message.pin`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+        """
+        return await self._get_message(action="pin").pin(
+            disable_notification=disable_notification,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def unpin_message(
+        self,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+            await update.callback_query.message.unpin(*args, **kwargs)
+
+        For the documentation of the arguments, please see :meth:`telegram.Message.unpin`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+        """
+        return await self._get_message(action="unpin").unpin(
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def copy_message(
+        self,
+        chat_id: Union[int, str],
+        caption: Optional[str] = None,
+        parse_mode: ODVInput[str] = DEFAULT_NONE,
+        caption_entities: Optional[Sequence["MessageEntity"]] = None,
+        disable_notification: ODVInput[bool] = DEFAULT_NONE,
+        reply_markup: Optional[ReplyMarkup] = None,
+        protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: Optional[int] = None,
+        reply_parameters: Optional["ReplyParameters"] = None,
+        show_caption_above_media: Optional[bool] = None,
+        *,
+        allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
+        reply_to_message_id: Optional[int] = None,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> "MessageId":
+        """Shortcut for::
+
+            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`.
+
+        .. versionchanged:: 20.8
+           Raises :exc:`TypeError` if :attr:`message` is not accessible.
+
+        Returns:
+            :class:`telegram.MessageId`: On success, returns the MessageId of the sent message.
+
+        Raises:
+            :exc:`TypeError` if :attr:`message` is not accessible.
+        """
+        return await self._get_message(action="copy").copy(
+            chat_id=chat_id,
+            caption=caption,
+            parse_mode=parse_mode,
+            caption_entities=caption_entities,
+            disable_notification=disable_notification,
+            reply_to_message_id=reply_to_message_id,
+            allow_sending_without_reply=allow_sending_without_reply,
+            reply_markup=reply_markup,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+            protect_content=protect_content,
+            message_thread_id=message_thread_id,
+            reply_parameters=reply_parameters,
+            show_caption_above_media=show_caption_above_media,
+        )
+
+    MAX_ANSWER_TEXT_LENGTH: Final[int] = (
+        constants.CallbackQueryLimit.ANSWER_CALLBACK_QUERY_TEXT_LENGTH
+    )
+    """
+    :const:`telegram.constants.CallbackQueryLimit.ANSWER_CALLBACK_QUERY_TEXT_LENGTH`
+
+    .. versionadded:: 13.2
+    """

_chatadministratorrights.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the class which represents a Telegram ChatAdministratorRights."""
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class ChatAdministratorRights(TelegramObject):
+    """Represents the rights of an administrator in a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`is_anonymous`, :attr:`can_manage_chat`,
+    :attr:`can_delete_messages`, :attr:`can_manage_video_chats`, :attr:`can_restrict_members`,
+    :attr:`can_promote_members`, :attr:`can_change_info`, :attr:`can_invite_users`,
+    :attr:`can_post_messages`, :attr:`can_edit_messages`, :attr:`can_pin_messages`,
+    :attr:`can_manage_topics`, :attr:`can_post_stories`, :attr:`can_delete_stories`, and
+    :attr:`can_edit_stories` are equal.
+
+    .. versionadded:: 20.0
+
+    .. versionchanged:: 20.0
+        :attr:`can_manage_topics` is considered as well when comparing objects of
+        this type in terms of equality.
+
+    .. versionchanged:: 20.6
+        :attr:`can_post_stories`, :attr:`can_edit_stories`, and :attr:`can_delete_stories` are
+        considered as well when comparing objects of this type in terms of equality.
+
+    .. versionchanged:: 21.1
+        As of this version, :attr:`can_post_stories`, :attr:`can_edit_stories`,
+        and :attr:`can_delete_stories` is now required. Thus, the order of arguments had to be
+        changed.
+
+    Args:
+        is_anonymous (:obj:`bool`): :obj:`True`, if the user's presence in the chat is hidden.
+        can_manage_chat (:obj:`bool`): :obj:`True`, if the administrator can access the chat event
+            log, get boost list, see hidden supergroup and channel members, report spam messages
+            and ignore slow mode. Implied by any other administrator privilege.
+        can_delete_messages (:obj:`bool`): :obj:`True`, if the administrator can delete messages of
+            other users.
+        can_manage_video_chats (:obj:`bool`): :obj:`True`, if the administrator can manage video
+            chats.
+        can_restrict_members (:obj:`bool`): :obj:`True`, if the administrator can restrict, ban or
+            unban chat members, or access supergroup statistics.
+        can_promote_members (:obj:`bool`): :obj:`True`, if the administrator can add new
+            administrators with a subset of their own privileges or demote administrators
+            that they have promoted, directly or indirectly (promoted by administrators that
+            were appointed by the user).
+        can_change_info (:obj:`bool`): :obj:`True`, if the user is allowed to change the chat title
+            , photo and other settings.
+        can_invite_users (:obj:`bool`): :obj:`True`, if the user is allowed to invite new users to
+            the chat.
+        can_post_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can post
+            messages in the channel, or access channel statistics; for channels only.
+        can_edit_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can edit
+            messages of other users and can pin messages; for channels only.
+        can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
+            messages; for groups and supergroups only.
+        can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
+            stories to the chat.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_delete_stories (:obj:`bool`): :obj:`True`, if the administrator can delete
+            stories posted by other users.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; for supergroups only.
+
+            .. versionadded:: 20.0
+
+    Attributes:
+        is_anonymous (:obj:`bool`): :obj:`True`, if the user's presence in the chat is hidden.
+        can_manage_chat (:obj:`bool`): :obj:`True`, if the administrator can access the chat event
+            log, get boost list, see hidden supergroup and channel members, report spam messages
+            and ignore slow mode. Implied by any other administrator privilege.
+        can_delete_messages (:obj:`bool`): :obj:`True`, if the administrator can delete messages of
+            other users.
+        can_manage_video_chats (:obj:`bool`): :obj:`True`, if the administrator can manage video
+            chats.
+        can_restrict_members (:obj:`bool`): :obj:`True`, if the administrator can restrict, ban or
+            unban chat members, or access supergroup statistics.
+        can_promote_members (:obj:`bool`): :obj:`True`, if the administrator can add new
+            administrators with a subset of their own privileges or demote administrators that he
+            has promoted, directly or indirectly (promoted by administrators that were appointed by
+            the user.)
+        can_change_info (:obj:`bool`): :obj:`True`, if the user is allowed to change the chat title
+            ,photo and other settings.
+        can_invite_users (:obj:`bool`): :obj:`True`, if the user is allowed to invite new users to
+            the chat.
+        can_post_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can post
+            messages in the channel, or access channel statistics; for channels only.
+        can_edit_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can edit
+            messages of other users and can pin messages; for channels only.
+        can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
+            messages; for groups and supergroups only.
+        can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
+            stories to the chat.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_delete_stories (:obj:`bool`): :obj:`True`, if the administrator can delete
+            stories posted by other users.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; for supergroups only.
+
+            .. versionadded:: 20.0
+    """
+
+    __slots__ = (
+        "can_change_info",
+        "can_delete_messages",
+        "can_delete_stories",
+        "can_edit_messages",
+        "can_edit_stories",
+        "can_invite_users",
+        "can_manage_chat",
+        "can_manage_topics",
+        "can_manage_video_chats",
+        "can_pin_messages",
+        "can_post_messages",
+        "can_post_stories",
+        "can_promote_members",
+        "can_restrict_members",
+        "is_anonymous",
+    )
+
+    def __init__(
+        self,
+        is_anonymous: bool,
+        can_manage_chat: bool,
+        can_delete_messages: bool,
+        can_manage_video_chats: bool,
+        can_restrict_members: bool,
+        can_promote_members: bool,
+        can_change_info: bool,
+        can_invite_users: bool,
+        can_post_stories: bool,
+        can_edit_stories: bool,
+        can_delete_stories: bool,
+        can_post_messages: Optional[bool] = None,
+        can_edit_messages: Optional[bool] = None,
+        can_pin_messages: Optional[bool] = None,
+        can_manage_topics: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> None:
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.is_anonymous: bool = is_anonymous
+        self.can_manage_chat: bool = can_manage_chat
+        self.can_delete_messages: bool = can_delete_messages
+        self.can_manage_video_chats: bool = can_manage_video_chats
+        self.can_restrict_members: bool = can_restrict_members
+        self.can_promote_members: bool = can_promote_members
+        self.can_change_info: bool = can_change_info
+        self.can_invite_users: bool = can_invite_users
+        self.can_post_stories: bool = can_post_stories
+        self.can_edit_stories: bool = can_edit_stories
+        self.can_delete_stories: bool = can_delete_stories
+        # Optionals
+        self.can_post_messages: Optional[bool] = can_post_messages
+        self.can_edit_messages: Optional[bool] = can_edit_messages
+        self.can_pin_messages: Optional[bool] = can_pin_messages
+        self.can_manage_topics: Optional[bool] = can_manage_topics
+
+        self._id_attrs = (
+            self.is_anonymous,
+            self.can_manage_chat,
+            self.can_delete_messages,
+            self.can_manage_video_chats,
+            self.can_restrict_members,
+            self.can_promote_members,
+            self.can_change_info,
+            self.can_invite_users,
+            self.can_post_messages,
+            self.can_edit_messages,
+            self.can_pin_messages,
+            self.can_manage_topics,
+            self.can_post_stories,
+            self.can_edit_stories,
+            self.can_delete_stories,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def all_rights(cls) -> "ChatAdministratorRights":
+        """
+        This method returns the :class:`ChatAdministratorRights` object with all attributes set to
+        :obj:`True`. This is e.g. useful when changing the bot's default administrator rights with
+        :meth:`telegram.Bot.set_my_default_administrator_rights`.
+
+        .. versionadded:: 20.0
+        """
+        return cls(*(True,) * len(cls.__slots__))
+
+    @classmethod
+    def no_rights(cls) -> "ChatAdministratorRights":
+        """
+        This method returns the :class:`ChatAdministratorRights` object with all attributes set to
+        :obj:`False`.
+
+        .. versionadded:: 20.0
+        """
+        return cls(*(False,) * len(cls.__slots__))

_chatbackground.py

@@ -0,0 +1,546 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains objects related to chat backgrounds."""
+from typing import TYPE_CHECKING, Dict, Final, Optional, Sequence, Tuple, Type
+
+from telegram import constants
+from telegram._files.document import Document
+from telegram._telegramobject import TelegramObject
+from telegram._utils import enum
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class BackgroundFill(TelegramObject):
+    """Base class for Telegram BackgroundFill Objects. It can be one of:
+
+    * :class:`telegram.BackgroundFillSolid`
+    * :class:`telegram.BackgroundFillGradient`
+    * :class:`telegram.BackgroundFillFreeformGradient`
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        type (:obj:`str`): Type of the background fill. Can be one of:
+            :attr:`~telegram.BackgroundFill.SOLID`, :attr:`~telegram.BackgroundFill.GRADIENT`
+            or :attr:`~telegram.BackgroundFill.FREEFORM_GRADIENT`.
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Can be one of:
+            :attr:`~telegram.BackgroundFill.SOLID`, :attr:`~telegram.BackgroundFill.GRADIENT`
+            or :attr:`~telegram.BackgroundFill.FREEFORM_GRADIENT`.
+    """
+
+    __slots__ = ("type",)
+
+    SOLID: Final[constants.BackgroundFillType] = constants.BackgroundFillType.SOLID
+    """:const:`telegram.constants.BackgroundFillType.SOLID`"""
+    GRADIENT: Final[constants.BackgroundFillType] = constants.BackgroundFillType.GRADIENT
+    """:const:`telegram.constants.BackgroundFillType.GRADIENT`"""
+    FREEFORM_GRADIENT: Final[constants.BackgroundFillType] = (
+        constants.BackgroundFillType.FREEFORM_GRADIENT
+    )
+    """:const:`telegram.constants.BackgroundFillType.FREEFORM_GRADIENT`"""
+
+    def __init__(
+        self,
+        type: str,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required by all subclasses
+        self.type: str = enum.get_member(constants.BackgroundFillType, type, type)
+
+        self._id_attrs = (self.type,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BackgroundFill"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[BackgroundFill]] = {
+            cls.SOLID: BackgroundFillSolid,
+            cls.GRADIENT: BackgroundFillGradient,
+            cls.FREEFORM_GRADIENT: BackgroundFillFreeformGradient,
+        }
+
+        if cls is BackgroundFill and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BackgroundFillSolid(BackgroundFill):
+    """
+    The background is filled using the selected color.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`color` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        color (:obj:`int`): The color of the background fill in the `RGB24` format.
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Always
+            :attr:`~telegram.BackgroundFill.SOLID`.
+        color (:obj:`int`): The color of the background fill in the `RGB24` format.
+    """
+
+    __slots__ = ("color",)
+
+    def __init__(
+        self,
+        color: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.SOLID, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.color: int = color
+
+            self._id_attrs = (self.color,)
+
+
+class BackgroundFillGradient(BackgroundFill):
+    """
+    The background is a gradient fill.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`top_color`, :attr:`bottom_color`
+    and :attr:`rotation_angle` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        top_color (:obj:`int`): Top color of the gradient in the `RGB24` format.
+        bottom_color (:obj:`int`): Bottom color of the gradient in the `RGB24` format.
+        rotation_angle (:obj:`int`): Clockwise rotation angle of the background
+            fill in degrees;
+            0-:tg-const:`telegram.constants.BackgroundFillLimit.MAX_ROTATION_ANGLE`.
+
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Always
+            :attr:`~telegram.BackgroundFill.GRADIENT`.
+        top_color (:obj:`int`): Top color of the gradient in the `RGB24` format.
+        bottom_color (:obj:`int`): Bottom color of the gradient in the `RGB24` format.
+        rotation_angle (:obj:`int`): Clockwise rotation angle of the background
+            fill in degrees;
+            0-:tg-const:`telegram.constants.BackgroundFillLimit.MAX_ROTATION_ANGLE`.
+    """
+
+    __slots__ = ("bottom_color", "rotation_angle", "top_color")
+
+    def __init__(
+        self,
+        top_color: int,
+        bottom_color: int,
+        rotation_angle: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.GRADIENT, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.top_color: int = top_color
+            self.bottom_color: int = bottom_color
+            self.rotation_angle: int = rotation_angle
+
+            self._id_attrs = (self.top_color, self.bottom_color, self.rotation_angle)
+
+
+class BackgroundFillFreeformGradient(BackgroundFill):
+    """
+    The background is a freeform gradient that rotates after every message in the chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`colors` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        colors (Sequence[:obj:`int`]): A list of the 3 or 4 base colors that are used to
+            generate the freeform gradient in the `RGB24` format
+
+    Attributes:
+        type (:obj:`str`): Type of the background fill. Always
+            :attr:`~telegram.BackgroundFill.FREEFORM_GRADIENT`.
+        colors (Sequence[:obj:`int`]): A list of the 3 or 4 base colors that are used to
+            generate the freeform gradient in the `RGB24` format
+    """
+
+    __slots__ = ("colors",)
+
+    def __init__(
+        self,
+        colors: Sequence[int],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.FREEFORM_GRADIENT, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.colors: Tuple[int, ...] = parse_sequence_arg(colors)
+
+            self._id_attrs = (self.colors,)
+
+
+class BackgroundType(TelegramObject):
+    """Base class for Telegram BackgroundType Objects. It can be one of:
+
+    * :class:`telegram.BackgroundTypeFill`
+    * :class:`telegram.BackgroundTypeWallpaper`
+    * :class:`telegram.BackgroundTypePattern`
+    * :class:`telegram.BackgroundTypeChatTheme`.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        type (:obj:`str`): Type of the background. Can be one of:
+            :attr:`~telegram.BackgroundType.FILL`, :attr:`~telegram.BackgroundType.WALLPAPER`
+            :attr:`~telegram.BackgroundType.PATTERN` or
+            :attr:`~telegram.BackgroundType.CHAT_THEME`.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Can be one of:
+            :attr:`~telegram.BackgroundType.FILL`, :attr:`~telegram.BackgroundType.WALLPAPER`
+            :attr:`~telegram.BackgroundType.PATTERN` or
+            :attr:`~telegram.BackgroundType.CHAT_THEME`.
+
+    """
+
+    __slots__ = ("type",)
+
+    FILL: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.FILL
+    """:const:`telegram.constants.BackgroundTypeType.FILL`"""
+    WALLPAPER: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.WALLPAPER
+    """:const:`telegram.constants.BackgroundTypeType.WALLPAPER`"""
+    PATTERN: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.PATTERN
+    """:const:`telegram.constants.BackgroundTypeType.PATTERN`"""
+    CHAT_THEME: Final[constants.BackgroundTypeType] = constants.BackgroundTypeType.CHAT_THEME
+    """:const:`telegram.constants.BackgroundTypeType.CHAT_THEME`"""
+
+    def __init__(
+        self,
+        type: str,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required by all subclasses
+        self.type: str = enum.get_member(constants.BackgroundTypeType, type, type)
+
+        self._id_attrs = (self.type,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["BackgroundType"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[BackgroundType]] = {
+            cls.FILL: BackgroundTypeFill,
+            cls.WALLPAPER: BackgroundTypeWallpaper,
+            cls.PATTERN: BackgroundTypePattern,
+            cls.CHAT_THEME: BackgroundTypeChatTheme,
+        }
+
+        if cls is BackgroundType and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+
+        if "fill" in data:
+            data["fill"] = BackgroundFill.de_json(data.get("fill"), bot)
+
+        if "document" in data:
+            data["document"] = Document.de_json(data.get("document"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class BackgroundTypeFill(BackgroundType):
+    """
+    The background is automatically filled based on the selected colors.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`fill` and :attr:`dark_theme_dimming` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        fill (:class:`telegram.BackgroundFill`): The background fill.
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.FILL`.
+        fill (:class:`telegram.BackgroundFill`): The background fill.
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+    """
+
+    __slots__ = ("dark_theme_dimming", "fill")
+
+    def __init__(
+        self,
+        fill: BackgroundFill,
+        dark_theme_dimming: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.FILL, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.fill: BackgroundFill = fill
+            self.dark_theme_dimming: int = dark_theme_dimming
+
+            self._id_attrs = (self.fill, self.dark_theme_dimming)
+
+
+class BackgroundTypeWallpaper(BackgroundType):
+    """
+    The background is a wallpaper in the `JPEG` format.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`document` and :attr:`dark_theme_dimming` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        document (:class:`telegram.Document`): Document with the wallpaper
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+        is_blurred (:obj:`bool`, optional): :obj:`True`, if the wallpaper is downscaled to fit
+            in a 450x450 square and then box-blurred with radius 12
+        is_moving (:obj:`bool`, optional): :obj:`True`, if the background moves slightly
+            when the device is tilted
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.WALLPAPER`.
+        document (:class:`telegram.Document`): Document with the wallpaper
+        dark_theme_dimming (:obj:`int`): Dimming of the background in dark themes, as a
+            percentage;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_DIMMING`.
+        is_blurred (:obj:`bool`): Optional. :obj:`True`, if the wallpaper is downscaled to fit
+            in a 450x450 square and then box-blurred with radius 12
+        is_moving (:obj:`bool`): Optional. :obj:`True`, if the background moves slightly
+            when the device is tilted
+    """
+
+    __slots__ = ("dark_theme_dimming", "document", "is_blurred", "is_moving")
+
+    def __init__(
+        self,
+        document: Document,
+        dark_theme_dimming: int,
+        is_blurred: Optional[bool] = None,
+        is_moving: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.WALLPAPER, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            # Required
+            self.document: Document = document
+            self.dark_theme_dimming: int = dark_theme_dimming
+            # Optionals
+            self.is_blurred: Optional[bool] = is_blurred
+            self.is_moving: Optional[bool] = is_moving
+
+            self._id_attrs = (self.document, self.dark_theme_dimming)
+
+
+class BackgroundTypePattern(BackgroundType):
+    """
+    The background is a `PNG` or `TGV` (gzipped subset of `SVG` with `MIME` type
+    `"application/x-tgwallpattern"`) pattern to be combined with the background fill
+    chosen by the user.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`document` and :attr:`fill` and :attr:`intensity` are equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        document (:class:`telegram.Document`): Document with the pattern.
+        fill (:class:`telegram.BackgroundFill`): The background fill that is combined with
+            the pattern.
+        intensity (:obj:`int`): Intensity of the pattern when it is shown above the filled
+            background;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_INTENSITY`.
+        is_inverted (:obj:`int`, optional): :obj:`True`, if the background fill must be applied
+            only to the pattern itself. All other pixels are black in this case. For dark
+            themes only.
+        is_moving (:obj:`bool`, optional): :obj:`True`, if the background moves slightly
+            when the device is tilted.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.PATTERN`.
+        document (:class:`telegram.Document`): Document with the pattern.
+        fill (:class:`telegram.BackgroundFill`): The background fill that is combined with
+            the pattern.
+        intensity (:obj:`int`): Intensity of the pattern when it is shown above the filled
+            background;
+            0-:tg-const:`telegram.constants.BackgroundTypeLimit.MAX_INTENSITY`.
+        is_inverted (:obj:`int`): Optional. :obj:`True`, if the background fill must be applied
+            only to the pattern itself. All other pixels are black in this case. For dark
+            themes only.
+        is_moving (:obj:`bool`): Optional. :obj:`True`, if the background moves slightly
+            when the device is tilted.
+    """
+
+    __slots__ = (
+        "document",
+        "fill",
+        "intensity",
+        "is_inverted",
+        "is_moving",
+    )
+
+    def __init__(
+        self,
+        document: Document,
+        fill: BackgroundFill,
+        intensity: int,
+        is_inverted: Optional[bool] = None,
+        is_moving: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.PATTERN, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            # Required
+            self.document: Document = document
+            self.fill: BackgroundFill = fill
+            self.intensity: int = intensity
+            # Optionals
+            self.is_inverted: Optional[bool] = is_inverted
+            self.is_moving: Optional[bool] = is_moving
+
+            self._id_attrs = (self.document, self.fill, self.intensity)
+
+
+class BackgroundTypeChatTheme(BackgroundType):
+    """
+    The background is taken directly from a built-in chat theme.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`theme_name` is equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        theme_name (:obj:`str`): Name of the chat theme, which is usually an emoji.
+
+    Attributes:
+        type (:obj:`str`): Type of the background. Always
+            :attr:`~telegram.BackgroundType.CHAT_THEME`.
+        theme_name (:obj:`str`): Name of the chat theme, which is usually an emoji.
+    """
+
+    __slots__ = ("theme_name",)
+
+    def __init__(
+        self,
+        theme_name: str,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.CHAT_THEME, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.theme_name: str = theme_name
+
+            self._id_attrs = (self.theme_name,)
+
+
+class ChatBackground(TelegramObject):
+    """
+    This object represents a chat background.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is  equal.
+
+    .. versionadded:: 21.2
+
+    Args:
+        type (:class:`telegram.BackgroundType`): Type of the background.
+
+    Attributes:
+        type (:class:`telegram.BackgroundType`): Type of the background.
+    """
+
+    __slots__ = ("type",)
+
+    def __init__(
+        self,
+        type: BackgroundType,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.type: BackgroundType = type
+
+        self._id_attrs = (self.type,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBackground"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["type"] = BackgroundType.de_json(data.get("type"), bot)
+
+        return super().de_json(data=data, bot=bot)

_chatboost.py

@@ -0,0 +1,451 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the classes that represent Telegram ChatBoosts."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Dict, Final, Optional, Sequence, Tuple, Type
+
+from telegram import constants
+from telegram._chat import Chat
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils import enum
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatBoostAdded(TelegramObject):
+    """
+    This object represents a service message about a user boosting a chat.
+
+    Objects of this class are comparable in terms of equality.
+    Two objects of this class are considered equal, if their
+    :attr:`boost_count` are equal.
+
+    .. versionadded:: 21.0
+
+    Args:
+        boost_count (:obj:`int`): Number of boosts added by the user.
+
+    Attributes:
+        boost_count (:obj:`int`): Number of boosts added by the user.
+
+    """
+
+    __slots__ = ("boost_count",)
+
+    def __init__(
+        self,
+        boost_count: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> None:
+        super().__init__(api_kwargs=api_kwargs)
+        self.boost_count: int = boost_count
+        self._id_attrs = (self.boost_count,)
+
+        self._freeze()
+
+
+class ChatBoostSource(TelegramObject):
+    """
+    Base class for Telegram ChatBoostSource objects. It can be one of:
+
+    * :class:`telegram.ChatBoostSourcePremium`
+    * :class:`telegram.ChatBoostSourceGiftCode`
+    * :class:`telegram.ChatBoostSourceGiveaway`
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`source` is equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        source (:obj:`str`): The source of the chat boost. Can be one of:
+            :attr:`~telegram.ChatBoostSource.PREMIUM`, :attr:`~telegram.ChatBoostSource.GIFT_CODE`,
+            or :attr:`~telegram.ChatBoostSource.GIVEAWAY`.
+
+    Attributes:
+        source (:obj:`str`): The source of the chat boost. Can be one of:
+            :attr:`~telegram.ChatBoostSource.PREMIUM`, :attr:`~telegram.ChatBoostSource.GIFT_CODE`,
+            or :attr:`~telegram.ChatBoostSource.GIVEAWAY`.
+    """
+
+    __slots__ = ("source",)
+
+    PREMIUM: Final[str] = constants.ChatBoostSources.PREMIUM
+    """:const:`telegram.constants.ChatBoostSources.PREMIUM`"""
+    GIFT_CODE: Final[str] = constants.ChatBoostSources.GIFT_CODE
+    """:const:`telegram.constants.ChatBoostSources.GIFT_CODE`"""
+    GIVEAWAY: Final[str] = constants.ChatBoostSources.GIVEAWAY
+    """:const:`telegram.constants.ChatBoostSources.GIVEAWAY`"""
+
+    def __init__(self, source: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+
+        # Required by all subclasses:
+        self.source: str = enum.get_member(constants.ChatBoostSources, source, source)
+
+        self._id_attrs = (self.source,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoostSource"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[ChatBoostSource]] = {
+            cls.PREMIUM: ChatBoostSourcePremium,
+            cls.GIFT_CODE: ChatBoostSourceGiftCode,
+            cls.GIVEAWAY: ChatBoostSourceGiveaway,
+        }
+
+        if cls is ChatBoostSource and data.get("source") in _class_mapping:
+            return _class_mapping[data.pop("source")].de_json(data=data, bot=bot)
+
+        if "user" in data:
+            data["user"] = User.de_json(data.get("user"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class ChatBoostSourcePremium(ChatBoostSource):
+    """
+    The boost was obtained by subscribing to Telegram Premium or by gifting a Telegram Premium
+    subscription to another user.
+
+    .. versionadded:: 20.8
+
+    Args:
+        user (:class:`telegram.User`): User that boosted the chat.
+
+    Attributes:
+        source (:obj:`str`): The source of the chat boost. Always
+            :attr:`~telegram.ChatBoostSource.PREMIUM`.
+        user (:class:`telegram.User`): User that boosted the chat.
+    """
+
+    __slots__ = ("user",)
+
+    def __init__(self, user: User, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(source=self.PREMIUM, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.user: User = user
+
+
+class ChatBoostSourceGiftCode(ChatBoostSource):
+    """
+    The boost was obtained by the creation of Telegram Premium gift codes to boost a chat. Each
+    such code boosts the chat 4 times for the duration of the corresponding Telegram Premium
+    subscription.
+
+    .. versionadded:: 20.8
+
+    Args:
+        user (:class:`telegram.User`): User for which the gift code was created.
+
+    Attributes:
+        source (:obj:`str`): The source of the chat boost. Always
+            :attr:`~telegram.ChatBoostSource.GIFT_CODE`.
+        user (:class:`telegram.User`): User for which the gift code was created.
+    """
+
+    __slots__ = ("user",)
+
+    def __init__(self, user: User, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(source=self.GIFT_CODE, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.user: User = user
+
+
+class ChatBoostSourceGiveaway(ChatBoostSource):
+    """
+    The boost was obtained by the creation of a Telegram Premium giveaway. This boosts the chat 4
+    times for the duration of the corresponding Telegram Premium subscription.
+
+    .. versionadded:: 20.8
+
+    Args:
+        giveaway_message_id (:obj:`int`): Identifier of a message in the chat with the giveaway;
+            the message could have been deleted already. May be 0 if the message isn't sent yet.
+        user (:class:`telegram.User`, optional): User that won the prize in the giveaway if any.
+        is_unclaimed (:obj:`bool`, optional): :obj:`True`, if the giveaway was completed, but
+            there was no user to win the prize.
+
+    Attributes:
+        source (:obj:`str`): Source of the boost. Always
+            :attr:`~telegram.ChatBoostSource.GIVEAWAY`.
+        giveaway_message_id (:obj:`int`): Identifier of a message in the chat with the giveaway;
+            the message could have been deleted already. May be 0 if the message isn't sent yet.
+        user (:class:`telegram.User`): Optional. User that won the prize in the giveaway if any.
+        is_unclaimed (:obj:`bool`): Optional. :obj:`True`, if the giveaway was completed, but
+            there was no user to win the prize.
+    """
+
+    __slots__ = ("giveaway_message_id", "is_unclaimed", "user")
+
+    def __init__(
+        self,
+        giveaway_message_id: int,
+        user: Optional[User] = None,
+        is_unclaimed: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(source=self.GIVEAWAY, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.giveaway_message_id: int = giveaway_message_id
+            self.user: Optional[User] = user
+            self.is_unclaimed: Optional[bool] = is_unclaimed
+
+
+class ChatBoost(TelegramObject):
+    """
+    This object contains information about a chat boost.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`boost_id`, :attr:`add_date`, :attr:`expiration_date`,
+    and :attr:`source` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        boost_id (:obj:`str`): Unique identifier of the boost.
+        add_date (:obj:`datetime.datetime`): Point in time when the chat was boosted.
+        expiration_date (:obj:`datetime.datetime`): Point in time when the boost
+            will automatically expire, unless the booster's Telegram Premium subscription is
+            prolonged.
+        source (:class:`telegram.ChatBoostSource`): Source of the added boost.
+
+    Attributes:
+        boost_id (:obj:`str`): Unique identifier of the boost.
+        add_date (:obj:`datetime.datetime`): Point in time when the chat was boosted.
+            |datetime_localization|
+        expiration_date (:obj:`datetime.datetime`): Point in time when the boost
+            will automatically expire, unless the booster's Telegram Premium subscription is
+            prolonged. |datetime_localization|
+        source (:class:`telegram.ChatBoostSource`): Source of the added boost.
+    """
+
+    __slots__ = ("add_date", "boost_id", "expiration_date", "source")
+
+    def __init__(
+        self,
+        boost_id: str,
+        add_date: datetime,
+        expiration_date: datetime,
+        source: ChatBoostSource,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.boost_id: str = boost_id
+        self.add_date: datetime = add_date
+        self.expiration_date: datetime = expiration_date
+        self.source: ChatBoostSource = source
+
+        self._id_attrs = (self.boost_id, self.add_date, self.expiration_date, self.source)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoost"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["source"] = ChatBoostSource.de_json(data.get("source"), bot)
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+        data["add_date"] = from_timestamp(data["add_date"], tzinfo=loc_tzinfo)
+        data["expiration_date"] = from_timestamp(data["expiration_date"], tzinfo=loc_tzinfo)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class ChatBoostUpdated(TelegramObject):
+    """This object represents a boost added to a chat or changed.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`chat`, and :attr:`boost` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        chat (:class:`telegram.Chat`): Chat which was boosted.
+        boost (:class:`telegram.ChatBoost`): Information about the chat boost.
+
+    Attributes:
+        chat (:class:`telegram.Chat`): Chat which was boosted.
+        boost (:class:`telegram.ChatBoost`): Information about the chat boost.
+    """
+
+    __slots__ = ("boost", "chat")
+
+    def __init__(
+        self,
+        chat: Chat,
+        boost: ChatBoost,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.chat: Chat = chat
+        self.boost: ChatBoost = boost
+
+        self._id_attrs = (self.chat.id, self.boost)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoostUpdated"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["boost"] = ChatBoost.de_json(data.get("boost"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class ChatBoostRemoved(TelegramObject):
+    """
+    This object represents a boost removed from a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`chat`, :attr:`boost_id`, :attr:`remove_date`, and
+    :attr:`source` are equal.
+
+    Args:
+        chat (:class:`telegram.Chat`): Chat which was boosted.
+        boost_id (:obj:`str`): Unique identifier of the boost.
+        remove_date (:obj:`datetime.datetime`): Point in time when the boost was removed.
+        source (:class:`telegram.ChatBoostSource`): Source of the removed boost.
+
+    Attributes:
+        chat (:class:`telegram.Chat`): Chat which was boosted.
+        boost_id (:obj:`str`): Unique identifier of the boost.
+        remove_date (:obj:`datetime.datetime`): Point in time when the boost was removed.
+            |datetime_localization|
+        source (:class:`telegram.ChatBoostSource`): Source of the removed boost.
+    """
+
+    __slots__ = ("boost_id", "chat", "remove_date", "source")
+
+    def __init__(
+        self,
+        chat: Chat,
+        boost_id: str,
+        remove_date: datetime,
+        source: ChatBoostSource,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.chat: Chat = chat
+        self.boost_id: str = boost_id
+        self.remove_date: datetime = remove_date
+        self.source: ChatBoostSource = source
+
+        self._id_attrs = (self.chat, self.boost_id, self.remove_date, self.source)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatBoostRemoved"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["source"] = ChatBoostSource.de_json(data.get("source"), bot)
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+        data["remove_date"] = from_timestamp(data["remove_date"], tzinfo=loc_tzinfo)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class UserChatBoosts(TelegramObject):
+    """This object represents a list of boosts added to a chat by a user.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`boosts` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        boosts (Sequence[:class:`telegram.ChatBoost`]): List of boosts added to the chat by the
+            user.
+
+    Attributes:
+        boosts (Tuple[:class:`telegram.ChatBoost`]): List of boosts added to the chat by the user.
+    """
+
+    __slots__ = ("boosts",)
+
+    def __init__(
+        self,
+        boosts: Sequence[ChatBoost],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.boosts: Tuple[ChatBoost, ...] = parse_sequence_arg(boosts)
+
+        self._id_attrs = (self.boosts,)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["UserChatBoosts"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["boosts"] = ChatBoost.de_list(data.get("boosts"), bot)
+
+        return super().de_json(data=data, bot=bot)

_chatfullinfo.py

@@ -0,0 +1,549 @@
+#!/usr/bin/env python
+# pylint: disable=redefined-builtin
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChatFullInfo."""
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+
+from telegram._birthdate import Birthdate
+from telegram._chat import Chat, _ChatBase
+from telegram._chatlocation import ChatLocation
+from telegram._chatpermissions import ChatPermissions
+from telegram._files.chatphoto import ChatPhoto
+from telegram._reaction import ReactionType
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot, BusinessIntro, BusinessLocation, BusinessOpeningHours, Message
+
+
+class ChatFullInfo(_ChatBase):
+    """
+    This object contains full information about a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`~telegram.Chat.id` is equal.
+
+    .. versionadded:: 21.2
+
+    .. versionchanged:: 21.3
+        Explicit support for all shortcut methods known from :class:`telegram.Chat` on this
+        object. Previously those were only available because this class inherited from
+        :class:`telegram.Chat`.
+
+    Args:
+        id (:obj:`int`): Unique identifier for this chat.
+        type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
+            :attr:`SUPERGROUP` or :attr:`CHANNEL`.
+        accent_color_id (:obj:`int`, optional): Identifier of the
+            :class:`accent color <telegram.constants.AccentColor>` for the chat name and
+            backgrounds of the chat photo, reply header, and link preview. See `accent colors`_
+            for more details.
+
+            .. versionadded:: 20.8
+        max_reaction_count (:obj:`int`): The maximum number of reactions that can be set on a
+            message in the chat.
+
+            .. versionadded:: 21.2
+        title (:obj:`str`, optional): Title, for supergroups, channels and group chats.
+        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.
+        is_forum (:obj:`bool`, optional): :obj:`True`, if the supergroup chat is a forum
+            (has topics_ enabled).
+
+            .. versionadded:: 20.0
+        photo (:class:`telegram.ChatPhoto`, optional): Chat photo.
+        active_usernames (Sequence[:obj:`str`], optional):  If set, the list of all `active chat
+            usernames <https://telegram.org/blog/topics-in-groups-collectible-usernames\
+            #collectible-usernames>`_; for private chats, supergroups and channels.
+
+            .. versionadded:: 20.0
+        birthdate (:class:`telegram.Birthdate`, optional): For private chats,
+            the date of birth of the user.
+
+            .. versionadded:: 21.1
+        business_intro (:class:`telegram.BusinessIntro`, optional): For private chats with
+            business accounts, the intro of the business.
+
+            .. versionadded:: 21.1
+        business_location (:class:`telegram.BusinessLocation`, optional): For private chats with
+            business accounts, the location of the business.
+
+            .. versionadded:: 21.1
+        business_opening_hours (:class:`telegram.BusinessOpeningHours`, optional): For private
+            chats with business accounts, the opening hours of the business.
+
+            .. versionadded:: 21.1
+        personal_chat (:class:`telegram.Chat`, optional): For private chats, the personal channel
+            of the user.
+
+            .. versionadded:: 21.1
+        available_reactions (Sequence[:class:`telegram.ReactionType`], optional): List of available
+            reactions allowed in the chat. If omitted, then all of
+            :const:`telegram.constants.ReactionEmoji` are allowed.
+
+            .. versionadded:: 20.8
+        background_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of emoji chosen
+            by the chat for the reply header and link preview background.
+
+            .. versionadded:: 20.8
+        profile_accent_color_id (:obj:`int`, optional): Identifier of the
+            :class:`accent color <telegram.constants.ProfileAccentColor>` for the chat's profile
+            background. See profile `accent colors`_ for more details.
+
+            .. versionadded:: 20.8
+        profile_background_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of
+            the emoji chosen by the chat for its profile background.
+
+            .. versionadded:: 20.8
+        emoji_status_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of emoji
+            status of the chat or the other party in a private chat.
+
+            .. versionadded:: 20.0
+        emoji_status_expiration_date (:class:`datetime.datetime`, optional): Expiration date of
+            emoji status of the chat or the other party in a private chat, as a datetime object,
+            if any.
+
+            |datetime_localization|
+
+            .. versionadded:: 20.5
+        bio (:obj:`str`, optional): Bio of the other party in a private chat.
+        has_private_forwards (:obj:`bool`, optional): :obj:`True`, if privacy settings of the other
+            party in the private chat allows to use ``tg://user?id=<user_id>`` links only in chats
+            with the user.
+
+            .. versionadded:: 13.9
+        has_restricted_voice_and_video_messages (:obj:`bool`, optional): :obj:`True`, if the
+            privacy settings of the other party restrict sending voice and video note messages
+            in the private chat.
+
+            .. versionadded:: 20.0
+        join_to_send_messages (:obj:`bool`, optional): :obj:`True`, if users need to join the
+            supergroup before they can send messages.
+
+            .. versionadded:: 20.0
+        join_by_request (:obj:`bool`, optional): :obj:`True`, if all users directly joining the
+            supergroup without using an invite link need to be approved by supergroup
+            administrators.
+
+            .. versionadded:: 20.0
+        description (:obj:`str`, optional): Description, for groups, supergroups and channel chats.
+        invite_link (:obj:`str`, optional): Primary invite link, for groups, supergroups and
+            channel.
+        pinned_message (:class:`telegram.Message`, optional): The most recent pinned message
+            (by sending date).
+        permissions (:class:`telegram.ChatPermissions`): Optional. Default chat member permissions,
+            for groups and supergroups.
+        slow_mode_delay (:obj:`int`, optional): For supergroups, the minimum allowed delay between
+            consecutive messages sent by each unprivileged user.
+        unrestrict_boost_count (:obj:`int`, optional): For supergroups, the minimum number of
+            boosts that a non-administrator user needs to add in order to ignore slow mode and chat
+            permissions.
+
+            .. versionadded:: 21.0
+        message_auto_delete_time (:obj:`int`, optional): The time after which all messages sent to
+            the chat will be automatically deleted; in seconds.
+
+            .. versionadded:: 13.4
+        has_aggressive_anti_spam_enabled (:obj:`bool`, optional): :obj:`True`, if aggressive
+            anti-spam checks are enabled in the supergroup. The field is only available to chat
+            administrators.
+
+            .. versionadded:: 20.0
+        has_hidden_members (:obj:`bool`, optional): :obj:`True`, if non-administrators can only
+            get the list of bots and administrators in the chat.
+
+            .. versionadded:: 20.0
+        has_protected_content (:obj:`bool`, optional): :obj:`True`, if messages from the chat can't
+            be forwarded to other chats.
+
+            .. versionadded:: 13.9
+        has_visible_history (:obj:`bool`, optional): :obj:`True`, if new chat members will have
+            access to old messages; available only to chat administrators.
+
+            .. versionadded:: 20.8
+        sticker_set_name (:obj:`str`, optional): For supergroups, name of group sticker set.
+        can_set_sticker_set (:obj:`bool`, optional): :obj:`True`, if the bot can change group the
+            sticker set.
+        custom_emoji_sticker_set_name (:obj:`str`, optional): For supergroups, the name of the
+            group's custom emoji sticker set. Custom emoji from this set can be used by all users
+            and bots in the group.
+
+            .. versionadded:: 21.0
+        linked_chat_id (:obj:`int`, optional): Unique identifier for the linked chat, i.e. the
+            discussion group identifier for a channel and vice versa; for supergroups and channel
+            chats.
+        location (:class:`telegram.ChatLocation`, optional): For supergroups, the location to which
+            the supergroup is connected.
+        can_send_paid_media (:obj:`bool`, optional): :obj:`True`, if paid media messages can be
+            sent or forwarded to the channel chat. The field is available only for channel chats.
+
+            .. versionadded:: 21.4
+
+    Attributes:
+        id (:obj:`int`): Unique identifier for this chat.
+        type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
+            :attr:`SUPERGROUP` or :attr:`CHANNEL`.
+        accent_color_id (:obj:`int`): Optional. Identifier of the
+            :class:`accent color <telegram.constants.AccentColor>` for the chat name and
+            backgrounds of the chat photo, reply header, and link preview. See `accent colors`_
+            for more details.
+
+            .. versionadded:: 20.8
+        max_reaction_count (:obj:`int`): The maximum number of reactions that can be set on a
+            message in the chat.
+
+            .. versionadded:: 21.2
+        title (:obj:`str`, optional): Title, for supergroups, channels and group chats.
+        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.
+        is_forum (:obj:`bool`, optional): :obj:`True`, if the supergroup chat is a forum
+            (has topics_ enabled).
+
+            .. versionadded:: 20.0
+        photo (:class:`telegram.ChatPhoto`): Optional. Chat photo.
+        active_usernames (Tuple[:obj:`str`]): Optional. If set, the list of all `active chat
+            usernames <https://telegram.org/blog/topics-in-groups-collectible-usernames\
+            #collectible-usernames>`_; for private chats, supergroups and channels.
+
+            This list is empty if the chat has no active usernames or this chat instance was not
+            obtained via :meth:`~telegram.Bot.get_chat`.
+
+            .. versionadded:: 20.0
+        birthdate (:class:`telegram.Birthdate`): Optional. For private chats,
+            the date of birth of the user.
+
+            .. versionadded:: 21.1
+        business_intro (:class:`telegram.BusinessIntro`): Optional. For private chats with
+            business accounts, the intro of the business.
+
+            .. versionadded:: 21.1
+        business_location (:class:`telegram.BusinessLocation`): Optional. For private chats with
+            business accounts, the location of the business.
+
+            .. versionadded:: 21.1
+        business_opening_hours (:class:`telegram.BusinessOpeningHours`): Optional. For private
+            chats with business accounts, the opening hours of the business.
+
+            .. versionadded:: 21.1
+        personal_chat (:class:`telegram.Chat`): Optional. For private chats, the personal channel
+            of the user.
+
+            .. versionadded:: 21.1
+        available_reactions (Tuple[:class:`telegram.ReactionType`]): Optional. List of available
+            reactions allowed in the chat. If omitted, then all of
+            :const:`telegram.constants.ReactionEmoji` are allowed.
+
+            .. versionadded:: 20.8
+        background_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of emoji chosen
+            by the chat for the reply header and link preview background.
+
+            .. versionadded:: 20.8
+        profile_accent_color_id (:obj:`int`): Optional. Identifier of the
+            :class:`accent color <telegram.constants.ProfileAccentColor>` for the chat's profile
+            background. See profile `accent colors`_ for more details.
+
+            .. versionadded:: 20.8
+        profile_background_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of
+            the emoji chosen by the chat for its profile background.
+
+            .. versionadded:: 20.8
+        emoji_status_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of emoji
+            status of the chat or the other party in a private chat.
+
+            .. versionadded:: 20.0
+        emoji_status_expiration_date (:class:`datetime.datetime`): Optional. Expiration date of
+            emoji status of the chat or the other party in a private chat, as a datetime object,
+            if any.
+
+            |datetime_localization|
+
+            .. versionadded:: 20.5
+        bio (:obj:`str`): Optional. Bio of the other party in a private chat.
+        has_private_forwards (:obj:`bool`): Optional. :obj:`True`, if privacy settings of the other
+            party in the private chat allows to use ``tg://user?id=<user_id>`` links only in chats
+            with the user.
+
+            .. versionadded:: 13.9
+        has_restricted_voice_and_video_messages (:obj:`bool`): Optional. :obj:`True`, if the
+            privacy settings of the other party restrict sending voice and video note messages
+            in the private chat.
+
+            .. versionadded:: 20.0
+        join_to_send_messages (:obj:`bool`): Optional. :obj:`True`, if users need to join
+            the supergroup before they can send messages.
+
+            .. versionadded:: 20.0
+        join_by_request (:obj:`bool`): Optional. :obj:`True`, if all users directly joining the
+            supergroup without using an invite link need to be approved by supergroup
+            administrators.
+
+            .. versionadded:: 20.0
+        description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats.
+        invite_link (:obj:`str`): Optional. Primary invite link, for groups, supergroups and
+            channel.
+        pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message
+            (by sending date).
+        permissions (:class:`telegram.ChatPermissions`): Optional. Default chat member permissions,
+            for groups and supergroups.
+        slow_mode_delay (:obj:`int`): Optional. For supergroups, the minimum allowed delay between
+            consecutive messages sent by each unprivileged user.
+        unrestrict_boost_count (:obj:`int`): Optional. For supergroups, the minimum number of
+            boosts that a non-administrator user needs to add in order to ignore slow mode and chat
+            permissions.
+
+            .. versionadded:: 21.0
+        message_auto_delete_time (:obj:`int`): Optional. The time after which all messages sent to
+            the chat will be automatically deleted; in seconds.
+
+            .. versionadded:: 13.4
+        has_aggressive_anti_spam_enabled (:obj:`bool`): Optional. :obj:`True`, if aggressive
+            anti-spam checks are enabled in the supergroup. The field is only available to chat
+            administrators.
+
+            .. versionadded:: 20.0
+        has_hidden_members (:obj:`bool`): Optional. :obj:`True`, if non-administrators can only
+            get the list of bots and administrators in the chat.
+
+            .. versionadded:: 20.0
+        has_protected_content (:obj:`bool`): Optional. :obj:`True`, if messages from the chat can't
+            be forwarded to other chats.
+
+            .. versionadded:: 13.9
+        has_visible_history (:obj:`bool`): Optional. :obj:`True`, if new chat members will have
+            access to old messages; available only to chat administrators.
+
+            .. versionadded:: 20.8
+        sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set.
+        can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the
+            sticker set.
+        custom_emoji_sticker_set_name (:obj:`str`): Optional. For supergroups, the name of the
+            group's custom emoji sticker set. Custom emoji from this set can be used by all users
+            and bots in the group.
+
+            .. versionadded:: 21.0
+        linked_chat_id (:obj:`int`): Optional. Unique identifier for the linked chat, i.e. the
+            discussion group identifier for a channel and vice versa; for supergroups and channel
+            chats.
+        location (:class:`telegram.ChatLocation`): Optional. For supergroups, the location to which
+            the supergroup is connected.
+        can_send_paid_media (:obj:`bool`): Optional. :obj:`True`, if paid media messages can be
+            sent or forwarded to the channel chat. The field is available only for channel chats.
+
+            .. versionadded:: 21.4
+
+    .. _accent colors: https://core.telegram.org/bots/api#accent-colors
+    .. _topics: https://telegram.org/blog/topics-in-groups-collectible-usernames#topics-in-groups
+    """
+
+    __slots__ = (
+        "accent_color_id",
+        "active_usernames",
+        "available_reactions",
+        "background_custom_emoji_id",
+        "bio",
+        "birthdate",
+        "business_intro",
+        "business_location",
+        "business_opening_hours",
+        "can_send_paid_media",
+        "can_set_sticker_set",
+        "custom_emoji_sticker_set_name",
+        "description",
+        "emoji_status_custom_emoji_id",
+        "emoji_status_expiration_date",
+        "has_aggressive_anti_spam_enabled",
+        "has_hidden_members",
+        "has_private_forwards",
+        "has_protected_content",
+        "has_restricted_voice_and_video_messages",
+        "has_visible_history",
+        "invite_link",
+        "join_by_request",
+        "join_to_send_messages",
+        "linked_chat_id",
+        "location",
+        "max_reaction_count",
+        "message_auto_delete_time",
+        "permissions",
+        "personal_chat",
+        "photo",
+        "pinned_message",
+        "profile_accent_color_id",
+        "profile_background_custom_emoji_id",
+        "slow_mode_delay",
+        "sticker_set_name",
+        "unrestrict_boost_count",
+    )
+
+    def __init__(
+        self,
+        id: int,
+        type: str,
+        accent_color_id: int,
+        max_reaction_count: int,
+        title: Optional[str] = None,
+        username: Optional[str] = None,
+        first_name: Optional[str] = None,
+        last_name: Optional[str] = None,
+        is_forum: Optional[bool] = None,
+        photo: Optional[ChatPhoto] = None,
+        active_usernames: Optional[Sequence[str]] = None,
+        birthdate: Optional[Birthdate] = None,
+        business_intro: Optional["BusinessIntro"] = None,
+        business_location: Optional["BusinessLocation"] = None,
+        business_opening_hours: Optional["BusinessOpeningHours"] = None,
+        personal_chat: Optional["Chat"] = None,
+        available_reactions: Optional[Sequence[ReactionType]] = None,
+        background_custom_emoji_id: Optional[str] = None,
+        profile_accent_color_id: Optional[int] = None,
+        profile_background_custom_emoji_id: Optional[str] = None,
+        emoji_status_custom_emoji_id: Optional[str] = None,
+        emoji_status_expiration_date: Optional[datetime] = None,
+        bio: Optional[str] = None,
+        has_private_forwards: Optional[bool] = None,
+        has_restricted_voice_and_video_messages: Optional[bool] = None,
+        join_to_send_messages: Optional[bool] = None,
+        join_by_request: Optional[bool] = None,
+        description: Optional[str] = None,
+        invite_link: Optional[str] = None,
+        pinned_message: Optional["Message"] = None,
+        permissions: Optional[ChatPermissions] = None,
+        slow_mode_delay: Optional[int] = None,
+        unrestrict_boost_count: Optional[int] = None,
+        message_auto_delete_time: Optional[int] = None,
+        has_aggressive_anti_spam_enabled: Optional[bool] = None,
+        has_hidden_members: Optional[bool] = None,
+        has_protected_content: Optional[bool] = None,
+        has_visible_history: Optional[bool] = None,
+        sticker_set_name: Optional[str] = None,
+        can_set_sticker_set: Optional[bool] = None,
+        custom_emoji_sticker_set_name: Optional[str] = None,
+        linked_chat_id: Optional[int] = None,
+        location: Optional[ChatLocation] = None,
+        can_send_paid_media: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(
+            id=id,
+            type=type,
+            title=title,
+            username=username,
+            first_name=first_name,
+            last_name=last_name,
+            is_forum=is_forum,
+            api_kwargs=api_kwargs,
+        )
+
+        # Required and unique to this class-
+        with self._unfrozen():
+            self.max_reaction_count: int = max_reaction_count
+            self.photo: Optional[ChatPhoto] = photo
+            self.bio: Optional[str] = bio
+            self.has_private_forwards: Optional[bool] = has_private_forwards
+            self.description: Optional[str] = description
+            self.invite_link: Optional[str] = invite_link
+            self.pinned_message: Optional[Message] = pinned_message
+            self.permissions: Optional[ChatPermissions] = permissions
+            self.slow_mode_delay: Optional[int] = slow_mode_delay
+            self.message_auto_delete_time: Optional[int] = (
+                int(message_auto_delete_time) if message_auto_delete_time is not None else None
+            )
+            self.has_protected_content: Optional[bool] = has_protected_content
+            self.has_visible_history: Optional[bool] = has_visible_history
+            self.sticker_set_name: Optional[str] = sticker_set_name
+            self.can_set_sticker_set: Optional[bool] = can_set_sticker_set
+            self.linked_chat_id: Optional[int] = linked_chat_id
+            self.location: Optional[ChatLocation] = location
+            self.join_to_send_messages: Optional[bool] = join_to_send_messages
+            self.join_by_request: Optional[bool] = join_by_request
+            self.has_restricted_voice_and_video_messages: Optional[bool] = (
+                has_restricted_voice_and_video_messages
+            )
+            self.active_usernames: Tuple[str, ...] = parse_sequence_arg(active_usernames)
+            self.emoji_status_custom_emoji_id: Optional[str] = emoji_status_custom_emoji_id
+            self.emoji_status_expiration_date: Optional[datetime] = emoji_status_expiration_date
+            self.has_aggressive_anti_spam_enabled: Optional[bool] = (
+                has_aggressive_anti_spam_enabled
+            )
+            self.has_hidden_members: Optional[bool] = has_hidden_members
+            self.available_reactions: Optional[Tuple[ReactionType, ...]] = parse_sequence_arg(
+                available_reactions
+            )
+            self.accent_color_id: Optional[int] = accent_color_id
+            self.background_custom_emoji_id: Optional[str] = background_custom_emoji_id
+            self.profile_accent_color_id: Optional[int] = profile_accent_color_id
+            self.profile_background_custom_emoji_id: Optional[str] = (
+                profile_background_custom_emoji_id
+            )
+            self.unrestrict_boost_count: Optional[int] = unrestrict_boost_count
+            self.custom_emoji_sticker_set_name: Optional[str] = custom_emoji_sticker_set_name
+            self.birthdate: Optional[Birthdate] = birthdate
+            self.personal_chat: Optional[Chat] = personal_chat
+            self.business_intro: Optional[BusinessIntro] = business_intro
+            self.business_location: Optional[BusinessLocation] = business_location
+            self.business_opening_hours: Optional[BusinessOpeningHours] = business_opening_hours
+            self.can_send_paid_media: Optional[bool] = can_send_paid_media
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatFullInfo"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["emoji_status_expiration_date"] = from_timestamp(
+            data.get("emoji_status_expiration_date"), tzinfo=loc_tzinfo
+        )
+
+        data["photo"] = ChatPhoto.de_json(data.get("photo"), bot)
+
+        from telegram import (  # pylint: disable=import-outside-toplevel
+            BusinessIntro,
+            BusinessLocation,
+            BusinessOpeningHours,
+            Message,
+        )
+
+        data["pinned_message"] = Message.de_json(data.get("pinned_message"), bot)
+        data["permissions"] = ChatPermissions.de_json(data.get("permissions"), bot)
+        data["location"] = ChatLocation.de_json(data.get("location"), bot)
+        data["available_reactions"] = ReactionType.de_list(data.get("available_reactions"), bot)
+        data["birthdate"] = Birthdate.de_json(data.get("birthdate"), bot)
+        data["personal_chat"] = Chat.de_json(data.get("personal_chat"), bot)
+        data["business_intro"] = BusinessIntro.de_json(data.get("business_intro"), bot)
+        data["business_location"] = BusinessLocation.de_json(data.get("business_location"), bot)
+        data["business_opening_hours"] = BusinessOpeningHours.de_json(
+            data.get("business_opening_hours"), bot
+        )
+
+        return super().de_json(data=data, bot=bot)

_chatinvitelink.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents an invite link for a chat."""
+import datetime
+from typing import TYPE_CHECKING, Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatInviteLink(TelegramObject):
+    """This object represents an invite link for a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`invite_link`, :attr:`creator`, :attr:`creates_join_request`,
+    :attr:`is_primary` and :attr:`is_revoked` are equal.
+
+    .. versionadded:: 13.4
+    .. versionchanged:: 20.0
+
+       * The argument & attribute :attr:`creates_join_request` is now required to comply with the
+         Bot API.
+       * Comparing objects of this class now also takes :attr:`creates_join_request` into account.
+
+    Args:
+        invite_link (:obj:`str`): The invite link.
+        creator (:class:`telegram.User`): Creator of the link.
+        creates_join_request (:obj:`bool`): :obj:`True`, if users joining the chat via
+            the link need to be approved by chat administrators.
+
+            .. versionadded:: 13.8
+        is_primary (:obj:`bool`): :obj:`True`, if the link is primary.
+        is_revoked (:obj:`bool`): :obj:`True`, if the link is revoked.
+        expire_date (:class:`datetime.datetime`, optional): Date when the link will expire or
+            has been expired.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        member_limit (:obj:`int`, optional): Maximum number of users that can be members of the
+            chat simultaneously after joining the chat via this invite link;
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`-
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`.
+        name (:obj:`str`, optional): Invite link name.
+            0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters.
+
+            .. versionadded:: 13.8
+        pending_join_request_count (:obj:`int`, optional): Number of pending join requests
+            created using this link.
+
+            .. versionadded:: 13.8
+        subscription_period (:obj:`int`, optional): The number of seconds the subscription will be
+            active for before the next payment.
+
+            .. versionadded:: 21.5
+        subscription_price (:obj:`int`, optional): The amount of Telegram Stars a user must pay
+            initially and after each subsequent subscription period to be a member of the chat
+            using the link.
+
+            .. versionadded:: 21.5
+
+    Attributes:
+        invite_link (:obj:`str`): The invite link. If the link was created by another chat
+            administrator, then the second part of the link will be replaced with ``'…'``.
+        creator (:class:`telegram.User`): Creator of the link.
+        creates_join_request (:obj:`bool`): :obj:`True`, if users joining the chat via
+            the link need to be approved by chat administrators.
+
+            .. versionadded:: 13.8
+        is_primary (:obj:`bool`): :obj:`True`, if the link is primary.
+        is_revoked (:obj:`bool`): :obj:`True`, if the link is revoked.
+        expire_date (:class:`datetime.datetime`): Optional. Date when the link will expire or
+            has been expired.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        member_limit (:obj:`int`): Optional. Maximum number of users that can be members
+            of the chat simultaneously after joining the chat via this invite link;
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`-
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`.
+        name (:obj:`str`): Optional. Invite link name.
+            0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters.
+
+            .. versionadded:: 13.8
+        pending_join_request_count (:obj:`int`): Optional. Number of pending join requests
+            created using this link.
+
+            .. versionadded:: 13.8
+        subscription_period (:obj:`int`): Optional. The number of seconds the subscription will be
+            active for before the next payment.
+
+            .. versionadded:: 21.5
+        subscription_price (:obj:`int`): Optional. The amount of Telegram Stars a user must pay
+            initially and after each subsequent subscription period to be a member of the chat
+            using the link.
+
+            .. versionadded:: 21.5
+
+    """
+
+    __slots__ = (
+        "creates_join_request",
+        "creator",
+        "expire_date",
+        "invite_link",
+        "is_primary",
+        "is_revoked",
+        "member_limit",
+        "name",
+        "pending_join_request_count",
+        "subscription_period",
+        "subscription_price",
+    )
+
+    def __init__(
+        self,
+        invite_link: str,
+        creator: User,
+        creates_join_request: bool,
+        is_primary: bool,
+        is_revoked: bool,
+        expire_date: Optional[datetime.datetime] = None,
+        member_limit: Optional[int] = None,
+        name: Optional[str] = None,
+        pending_join_request_count: Optional[int] = None,
+        subscription_period: Optional[int] = None,
+        subscription_price: Optional[int] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.invite_link: str = invite_link
+        self.creator: User = creator
+        self.creates_join_request: bool = creates_join_request
+        self.is_primary: bool = is_primary
+        self.is_revoked: bool = is_revoked
+
+        # Optionals
+        self.expire_date: Optional[datetime.datetime] = expire_date
+        self.member_limit: Optional[int] = member_limit
+        self.name: Optional[str] = name
+        self.pending_join_request_count: Optional[int] = (
+            int(pending_join_request_count) if pending_join_request_count is not None else None
+        )
+        self.subscription_period: Optional[int] = subscription_period
+        self.subscription_price: Optional[int] = subscription_price
+
+        self._id_attrs = (
+            self.invite_link,
+            self.creates_join_request,
+            self.creator,
+            self.is_primary,
+            self.is_revoked,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatInviteLink"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["creator"] = User.de_json(data.get("creator"), bot)
+        data["expire_date"] = from_timestamp(data.get("expire_date", None), tzinfo=loc_tzinfo)
+
+        return super().de_json(data=data, bot=bot)

_chatjoinrequest.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChatJoinRequest."""
+import datetime
+from typing import TYPE_CHECKING, Optional
+
+from telegram._chat import Chat
+from telegram._chatinvitelink import ChatInviteLink
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.defaultvalue import DEFAULT_NONE
+from telegram._utils.types import JSONDict, ODVInput
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatJoinRequest(TelegramObject):
+    """This object represents a join request sent to a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`chat`, :attr:`from_user` and :attr:`date` are equal.
+
+    Note:
+        * Since Bot API 5.5, bots are allowed to contact users who sent a join request to a chat
+          where the bot is an administrator with the
+          :attr:`~telegram.ChatMemberAdministrator.can_invite_users` administrator right - even
+          if the user never interacted with the bot before.
+        * Telegram does not guarantee that :attr:`from_user.id <from_user>` coincides with the
+          ``chat_id`` of the user. Please use :attr:`user_chat_id` to contact the user in
+          response to their join request.
+
+    .. versionadded:: 13.8
+    .. versionchanged:: 20.1
+       In Bot API 6.5 the argument :paramref:`user_chat_id` was added, which changes the position
+       of the optional arguments :paramref:`bio` and :paramref:`invite_link`.
+
+    Args:
+        chat (:class:`telegram.Chat`): Chat to which the request was sent.
+        from_user (:class:`telegram.User`): User that sent the join request.
+        date (:class:`datetime.datetime`): Date the request was sent.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        user_chat_id (:obj:`int`): Identifier of a private chat with the user who sent the join
+            request. This number may have more than 32 significant bits and some programming
+            languages may have difficulty/silent defects in interpreting it. But it has at most 52
+            significant bits, so a 64-bit integer or double-precision float type are safe for
+            storing this identifier. The bot can use this identifier for 5 minutes to send messages
+            until the join request is processed, assuming no other administrator contacted the
+            user.
+
+            .. versionadded:: 20.1
+        bio (:obj:`str`, optional): Bio of the user.
+        invite_link (:class:`telegram.ChatInviteLink`, optional): Chat invite link that was used
+            by the user to send the join request.
+
+    Attributes:
+        chat (:class:`telegram.Chat`): Chat to which the request was sent.
+        from_user (:class:`telegram.User`): User that sent the join request.
+        date (:class:`datetime.datetime`): Date the request was sent.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        user_chat_id (:obj:`int`): Identifier of a private chat with the user who sent the join
+            request. This number may have more than 32 significant bits and some programming
+            languages may have difficulty/silent defects in interpreting it. But it has at most 52
+            significant bits, so a 64-bit integer or double-precision float type are safe for
+            storing this identifier. The bot can use this identifier for 24 hours to send messages
+            until the join request is processed, assuming no other administrator contacted the
+            user.
+
+            .. versionadded:: 20.1
+        bio (:obj:`str`): Optional. Bio of the user.
+        invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link that was used
+            by the user to send the join request.
+
+            Note:
+                When a user joins a *public* group via an invite link, this attribute may not
+                be present. However, this behavior is undocument and may be subject to change.
+                See `this GitHub thread <https://github.com/tdlib/telegram-bot-api/issues/428>`_
+                for some discussion.
+
+    """
+
+    __slots__ = ("bio", "chat", "date", "from_user", "invite_link", "user_chat_id")
+
+    def __init__(
+        self,
+        chat: Chat,
+        from_user: User,
+        date: datetime.datetime,
+        user_chat_id: int,
+        bio: Optional[str] = None,
+        invite_link: Optional[ChatInviteLink] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.chat: Chat = chat
+        self.from_user: User = from_user
+        self.date: datetime.datetime = date
+        self.user_chat_id: int = user_chat_id
+
+        # Optionals
+        self.bio: Optional[str] = bio
+        self.invite_link: Optional[ChatInviteLink] = invite_link
+
+        self._id_attrs = (self.chat, self.from_user, self.date)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatJoinRequest"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        data["date"] = from_timestamp(data.get("date", None), tzinfo=loc_tzinfo)
+        data["invite_link"] = ChatInviteLink.de_json(data.get("invite_link"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+    async def approve(
+        self,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+            await bot.approve_chat_join_request(
+                chat_id=update.effective_chat.id, user_id=update.effective_user.id, *args, **kwargs
+            )
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.approve_chat_join_request`.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        """
+        return await self.get_bot().approve_chat_join_request(
+            chat_id=self.chat.id,
+            user_id=self.from_user.id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def decline(
+        self,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """Shortcut for::
+
+            await bot.decline_chat_join_request(
+                chat_id=update.effective_chat.id, user_id=update.effective_user.id, *args, **kwargs
+            )
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.decline_chat_join_request`.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        """
+        return await self.get_bot().decline_chat_join_request(
+            chat_id=self.chat.id,
+            user_id=self.from_user.id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )

_chatlocation.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a location to which a chat is connected."""
+
+from typing import TYPE_CHECKING, Final, Optional
+
+from telegram import constants
+from telegram._files.location import Location
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatLocation(TelegramObject):
+    """This object represents a location to which a chat is connected.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`location` is equal.
+
+    Args:
+        location (:class:`telegram.Location`): The location to which the supergroup is connected.
+            Can't be a live location.
+        address (:obj:`str`): Location address;
+            :tg-const:`telegram.ChatLocation.MIN_ADDRESS`-
+            :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner.
+    Attributes:
+        location (:class:`telegram.Location`): The location to which the supergroup is connected.
+            Can't be a live location.
+        address (:obj:`str`): Location address;
+            :tg-const:`telegram.ChatLocation.MIN_ADDRESS`-
+            :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner.
+
+    """
+
+    __slots__ = ("address", "location")
+
+    def __init__(
+        self,
+        location: Location,
+        address: str,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.location: Location = location
+        self.address: str = address
+
+        self._id_attrs = (self.location,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatLocation"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["location"] = Location.de_json(data.get("location"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+    MIN_ADDRESS: Final[int] = constants.LocationLimit.MIN_CHAT_LOCATION_ADDRESS
+    """:const:`telegram.constants.LocationLimit.MIN_CHAT_LOCATION_ADDRESS`
+
+    .. versionadded:: 20.0
+    """
+    MAX_ADDRESS: Final[int] = constants.LocationLimit.MAX_CHAT_LOCATION_ADDRESS
+    """:const:`telegram.constants.LocationLimit.MAX_CHAT_LOCATION_ADDRESS`
+
+    .. versionadded:: 20.0
+    """

_chatmember.py

@@ -0,0 +1,665 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChatMember."""
+
+import datetime
+from typing import TYPE_CHECKING, Dict, Final, Optional, Type
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatMember(TelegramObject):
+    """Base class for Telegram ChatMember Objects.
+    Currently, the following 6 types of chat members are supported:
+
+    * :class:`telegram.ChatMemberOwner`
+    * :class:`telegram.ChatMemberAdministrator`
+    * :class:`telegram.ChatMemberMember`
+    * :class:`telegram.ChatMemberRestricted`
+    * :class:`telegram.ChatMemberLeft`
+    * :class:`telegram.ChatMemberBanned`
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`user` and :attr:`status` are equal.
+
+    Examples:
+        :any:`Chat Member Bot <examples.chatmemberbot>`
+
+    .. 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
+          use :class:`ChatMember` directly.
+        * The constant ``ChatMember.CREATOR`` was replaced by :attr:`~telegram.ChatMember.OWNER`
+        * The constant ``ChatMember.KICKED`` was replaced by :attr:`~telegram.ChatMember.BANNED`
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+        status (:obj:`str`): The member's status in the chat. Can be
+            :attr:`~telegram.ChatMember.ADMINISTRATOR`, :attr:`~telegram.ChatMember.OWNER`,
+            :attr:`~telegram.ChatMember.BANNED`, :attr:`~telegram.ChatMember.LEFT`,
+            :attr:`~telegram.ChatMember.MEMBER` or :attr:`~telegram.ChatMember.RESTRICTED`.
+
+    Attributes:
+        user (:class:`telegram.User`): Information about the user.
+        status (:obj:`str`): The member's status in the chat. Can be
+            :attr:`~telegram.ChatMember.ADMINISTRATOR`, :attr:`~telegram.ChatMember.OWNER`,
+            :attr:`~telegram.ChatMember.BANNED`, :attr:`~telegram.ChatMember.LEFT`,
+            :attr:`~telegram.ChatMember.MEMBER` or :attr:`~telegram.ChatMember.RESTRICTED`.
+
+    """
+
+    __slots__ = ("status", "user")
+
+    ADMINISTRATOR: Final[str] = constants.ChatMemberStatus.ADMINISTRATOR
+    """:const:`telegram.constants.ChatMemberStatus.ADMINISTRATOR`"""
+    OWNER: Final[str] = constants.ChatMemberStatus.OWNER
+    """:const:`telegram.constants.ChatMemberStatus.OWNER`"""
+    BANNED: Final[str] = constants.ChatMemberStatus.BANNED
+    """:const:`telegram.constants.ChatMemberStatus.BANNED`"""
+    LEFT: Final[str] = constants.ChatMemberStatus.LEFT
+    """:const:`telegram.constants.ChatMemberStatus.LEFT`"""
+    MEMBER: Final[str] = constants.ChatMemberStatus.MEMBER
+    """:const:`telegram.constants.ChatMemberStatus.MEMBER`"""
+    RESTRICTED: Final[str] = constants.ChatMemberStatus.RESTRICTED
+    """:const:`telegram.constants.ChatMemberStatus.RESTRICTED`"""
+
+    def __init__(
+        self,
+        user: User,
+        status: str,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required by all subclasses
+        self.user: User = user
+        self.status: str = status
+
+        self._id_attrs = (self.user, self.status)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatMember"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[ChatMember]] = {
+            cls.OWNER: ChatMemberOwner,
+            cls.ADMINISTRATOR: ChatMemberAdministrator,
+            cls.MEMBER: ChatMemberMember,
+            cls.RESTRICTED: ChatMemberRestricted,
+            cls.LEFT: ChatMemberLeft,
+            cls.BANNED: ChatMemberBanned,
+        }
+
+        if cls is ChatMember and data.get("status") in _class_mapping:
+            return _class_mapping[data.pop("status")].de_json(data=data, bot=bot)
+
+        data["user"] = User.de_json(data.get("user"), bot)
+        if "until_date" in data:
+            # Get the local timezone from the bot if it has defaults
+            loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+            data["until_date"] = from_timestamp(data["until_date"], tzinfo=loc_tzinfo)
+
+        # This is a deprecated field that TG still returns for backwards compatibility
+        # Let's filter it out to speed up the de-json process
+        if cls is ChatMemberRestricted and data.get("can_send_media_messages") is not None:
+            api_kwargs = {"can_send_media_messages": data.pop("can_send_media_messages")}
+            return super()._de_json(data=data, bot=bot, api_kwargs=api_kwargs)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class ChatMemberOwner(ChatMember):
+    """
+    Represents a chat member that owns the chat
+    and has all administrator privileges.
+
+    .. versionadded:: 13.7
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+        is_anonymous (:obj:`bool`): :obj:`True`, if the
+            user's presence in the chat is hidden.
+        custom_title (:obj:`str`, optional): Custom title for this user.
+
+    Attributes:
+        status (:obj:`str`): The member's status in the chat,
+            always :tg-const:`telegram.ChatMember.OWNER`.
+        user (:class:`telegram.User`): Information about the user.
+        is_anonymous (:obj:`bool`): :obj:`True`, if the user's
+            presence in the chat is hidden.
+        custom_title (:obj:`str`): Optional. Custom title for
+            this user.
+    """
+
+    __slots__ = ("custom_title", "is_anonymous")
+
+    def __init__(
+        self,
+        user: User,
+        is_anonymous: bool,
+        custom_title: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(status=ChatMember.OWNER, user=user, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.is_anonymous: bool = is_anonymous
+            self.custom_title: Optional[str] = custom_title
+
+
+class ChatMemberAdministrator(ChatMember):
+    """
+    Represents a chat member that has some additional privileges.
+
+    .. versionadded:: 13.7
+    .. versionchanged:: 20.0
+
+       * Argument and attribute ``can_manage_voice_chats`` were renamed to
+         :paramref:`can_manage_video_chats` and  :attr:`can_manage_video_chats` in accordance to
+         Bot API 6.0.
+       * The argument :paramref:`can_manage_topics` was added, which changes the position of the
+         optional argument :paramref:`custom_title`.
+
+    .. versionchanged:: 21.1
+        As of this version, :attr:`can_post_stories`, :attr:`can_edit_stories`,
+        and :attr:`can_delete_stories` is now required. Thus, the order of arguments had to be
+        changed.
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+        can_be_edited (:obj:`bool`): :obj:`True`, if the bot
+            is allowed to edit administrator privileges of that user.
+        is_anonymous (:obj:`bool`): :obj:`True`, if the  user's
+            presence in the chat is hidden.
+        can_manage_chat (:obj:`bool`): :obj:`True`, if the administrator can access the chat event
+            log, get boost list, see hidden supergroup and channel members, report spam messages
+            and ignore slow mode. Implied by any other administrator privilege.
+        can_delete_messages (:obj:`bool`): :obj:`True`, if the
+            administrator can delete messages of other users.
+        can_manage_video_chats (:obj:`bool`): :obj:`True`, if the
+            administrator can manage video chats.
+
+            .. versionadded:: 20.0
+        can_restrict_members (:obj:`bool`): :obj:`True`, if the
+            administrator can restrict, ban or unban chat members.
+        can_promote_members (:obj:`bool`): :obj:`True`, if the administrator
+            can add new administrators with a subset of his own privileges or demote
+            administrators that he has promoted, directly or indirectly (promoted by
+            administrators that were appointed by the user).
+        can_change_info (:obj:`bool`): :obj:`True`, if the user can change
+            the chat title, photo and other settings.
+        can_invite_users (:obj:`bool`): :obj:`True`, if the user can invite
+            new users to the chat.
+        can_post_messages (:obj:`bool`, optional): :obj:`True`, if the
+            administrator can post messages in the channel, or access channel statistics;
+            for channels only.
+        can_edit_messages (:obj:`bool`, optional): :obj:`True`, if the
+            administrator can edit messages of other users and can pin
+            messages; for channels only.
+        can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to pin messages; for groups and supergroups only.
+        can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
+            stories to the chat.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_delete_stories (:obj:`bool`): :obj:`True`, if the administrator can delete
+            stories posted by other users.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; for supergroups only.
+
+            .. versionadded:: 20.0
+        custom_title (:obj:`str`, optional): Custom title for this user.
+
+    Attributes:
+        status (:obj:`str`): The member's status in the chat,
+            always :tg-const:`telegram.ChatMember.ADMINISTRATOR`.
+        user (:class:`telegram.User`): Information about the user.
+        can_be_edited (:obj:`bool`): :obj:`True`, if the bot
+            is allowed to edit administrator privileges of that user.
+        is_anonymous (:obj:`bool`): :obj:`True`, if the  user's
+            presence in the chat is hidden.
+        can_manage_chat (:obj:`bool`): :obj:`True`, if the administrator can access the chat event
+            log, get boost list, see hidden supergroup and channel members, report spam messages
+            and ignore slow mode. Implied by any other administrator privilege.
+        can_delete_messages (:obj:`bool`): :obj:`True`, if the
+            administrator can delete messages of other users.
+        can_manage_video_chats (:obj:`bool`): :obj:`True`, if the
+            administrator can manage video chats.
+
+            .. versionadded:: 20.0
+        can_restrict_members (:obj:`bool`): :obj:`True`, if the
+            administrator can restrict, ban or unban chat members, or access supergroup statistics.
+        can_promote_members (:obj:`bool`): :obj:`True`, if the administrator can add new
+            administrators with a subset of their own privileges or demote administrators
+            that they have promoted, directly or indirectly (promoted by administrators that
+            were appointed by the user).
+        can_change_info (:obj:`bool`): :obj:`True`, if the user can change
+            the chat title, photo and other settings.
+        can_invite_users (:obj:`bool`): :obj:`True`, if the user can invite
+            new users to the chat.
+        can_post_messages (:obj:`bool`): Optional. :obj:`True`, if the
+            administrator can post messages in the channel or access channel statistics;
+            for channels only.
+        can_edit_messages (:obj:`bool`): Optional. :obj:`True`, if the
+            administrator can edit messages of other users and can pin
+            messages; for channels only.
+        can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to pin messages; for groups and supergroups only.
+        can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
+            stories to the chat.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_edit_stories (:obj:`bool`): :obj:`True`, if the administrator can edit stories posted
+            by other users, post stories to the chat page, pin chat stories, and access the chat's
+            story archive
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_delete_stories (:obj:`bool`): :obj:`True`, if the administrator can delete
+            stories posted by other users.
+
+            .. versionadded:: 20.6
+            .. versionchanged:: 21.0
+                |non_optional_story_argument|
+        can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; for supergroups only
+
+            .. versionadded:: 20.0
+        custom_title (:obj:`str`): Optional. Custom title for this user.
+    """
+
+    __slots__ = (
+        "can_be_edited",
+        "can_change_info",
+        "can_delete_messages",
+        "can_delete_stories",
+        "can_edit_messages",
+        "can_edit_stories",
+        "can_invite_users",
+        "can_manage_chat",
+        "can_manage_topics",
+        "can_manage_video_chats",
+        "can_pin_messages",
+        "can_post_messages",
+        "can_post_stories",
+        "can_promote_members",
+        "can_restrict_members",
+        "custom_title",
+        "is_anonymous",
+    )
+
+    def __init__(
+        self,
+        user: User,
+        can_be_edited: bool,
+        is_anonymous: bool,
+        can_manage_chat: bool,
+        can_delete_messages: bool,
+        can_manage_video_chats: bool,
+        can_restrict_members: bool,
+        can_promote_members: bool,
+        can_change_info: bool,
+        can_invite_users: bool,
+        can_post_stories: bool,
+        can_edit_stories: bool,
+        can_delete_stories: bool,
+        can_post_messages: Optional[bool] = None,
+        can_edit_messages: Optional[bool] = None,
+        can_pin_messages: Optional[bool] = None,
+        can_manage_topics: Optional[bool] = None,
+        custom_title: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(status=ChatMember.ADMINISTRATOR, user=user, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.can_be_edited: bool = can_be_edited
+            self.is_anonymous: bool = is_anonymous
+            self.can_manage_chat: bool = can_manage_chat
+            self.can_delete_messages: bool = can_delete_messages
+            self.can_manage_video_chats: bool = can_manage_video_chats
+            self.can_restrict_members: bool = can_restrict_members
+            self.can_promote_members: bool = can_promote_members
+            self.can_change_info: bool = can_change_info
+            self.can_invite_users: bool = can_invite_users
+            self.can_post_stories: bool = can_post_stories
+            self.can_edit_stories: bool = can_edit_stories
+            self.can_delete_stories: bool = can_delete_stories
+            # Optionals
+            self.can_post_messages: Optional[bool] = can_post_messages
+            self.can_edit_messages: Optional[bool] = can_edit_messages
+            self.can_pin_messages: Optional[bool] = can_pin_messages
+            self.can_manage_topics: Optional[bool] = can_manage_topics
+            self.custom_title: Optional[str] = custom_title
+
+
+class ChatMemberMember(ChatMember):
+    """
+    Represents a chat member that has no additional
+    privileges or restrictions.
+
+    .. versionadded:: 13.7
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+        until_date (:class:`datetime.datetime`, optional): Date when the user's subscription will
+            expire.
+
+            .. versionadded:: 21.5
+
+    Attributes:
+        status (:obj:`str`): The member's status in the chat,
+            always :tg-const:`telegram.ChatMember.MEMBER`.
+        user (:class:`telegram.User`): Information about the user.
+        until_date (:class:`datetime.datetime`): Optional. Date when the user's subscription will
+            expire.
+
+            .. versionadded:: 21.5
+
+    """
+
+    __slots__ = ("until_date",)
+
+    def __init__(
+        self,
+        user: User,
+        until_date: Optional[datetime.datetime] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(status=ChatMember.MEMBER, user=user, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.until_date: Optional[datetime.datetime] = until_date
+
+
+class ChatMemberRestricted(ChatMember):
+    """
+    Represents a chat member that is under certain restrictions
+    in the chat. Supergroups only.
+
+    .. versionadded:: 13.7
+    .. versionchanged:: 20.0
+       All arguments were made positional and their order was changed.
+       The argument can_manage_topics was added.
+
+    .. versionchanged:: 20.5
+      Removed deprecated argument and attribute ``can_send_media_messages``.
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+        is_member (:obj:`bool`): :obj:`True`, if the user is a
+            member of the chat at the moment of the request.
+        can_change_info (:obj:`bool`): :obj:`True`, if the user can change
+            the chat title, photo and other settings.
+        can_invite_users (:obj:`bool`): :obj:`True`, if the user can invite
+            new users to the chat.
+        can_pin_messages (:obj:`bool`): :obj:`True`, if the user is allowed
+            to pin messages; groups and supergroups only.
+        can_send_messages (:obj:`bool`): :obj:`True`, if the user is allowed
+            to send text messages, contacts, invoices, locations and venues.
+        can_send_polls (:obj:`bool`): :obj:`True`, if the user is allowed
+            to send polls.
+        can_send_other_messages (:obj:`bool`): :obj:`True`, if the user is allowed
+            to send animations, games, stickers and use inline bots.
+        can_add_web_page_previews (:obj:`bool`): :obj:`True`, if the user is
+           allowed to add web page previews to their messages.
+        can_manage_topics (:obj:`bool`): :obj:`True`, if the user is allowed to create
+            forum topics.
+
+            .. versionadded:: 20.0
+        until_date (:class:`datetime.datetime`): Date when restrictions
+           will be lifted for this user.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        can_send_audios (:obj:`bool`): :obj:`True`, if the user is allowed to send audios.
+
+            .. versionadded:: 20.1
+        can_send_documents (:obj:`bool`): :obj:`True`, if the user is allowed to send documents.
+
+            .. versionadded:: 20.1
+        can_send_photos (:obj:`bool`): :obj:`True`, if the user is allowed to send photos.
+
+            .. versionadded:: 20.1
+        can_send_videos (:obj:`bool`): :obj:`True`, if the user is allowed to send videos.
+
+            .. versionadded:: 20.1
+        can_send_video_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send video
+            notes.
+
+            .. versionadded:: 20.1
+        can_send_voice_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send voice
+            notes.
+
+            .. versionadded:: 20.1
+
+    Attributes:
+        status (:obj:`str`): The member's status in the chat,
+            always :tg-const:`telegram.ChatMember.RESTRICTED`.
+        user (:class:`telegram.User`): Information about the user.
+        is_member (:obj:`bool`): :obj:`True`, if the user is a
+            member of the chat at the moment of the request.
+        can_change_info (:obj:`bool`): :obj:`True`, if the user can change
+            the chat title, photo and other settings.
+        can_invite_users (:obj:`bool`): :obj:`True`, if the user can invite
+            new users to the chat.
+        can_pin_messages (:obj:`bool`): :obj:`True`, if the user is allowed
+            to pin messages; groups and supergroups only.
+        can_send_messages (:obj:`bool`): :obj:`True`, if the user is allowed
+            to send text messages, contacts, locations and venues.
+        can_send_polls (:obj:`bool`): :obj:`True`, if the user is allowed
+            to send polls.
+        can_send_other_messages (:obj:`bool`): :obj:`True`, if the user is allowed
+            to send animations, games, stickers and use inline bots.
+        can_add_web_page_previews (:obj:`bool`): :obj:`True`, if the user is
+           allowed to add web page previews to their messages.
+        can_manage_topics (:obj:`bool`): :obj:`True`, if the user is allowed to create
+            forum topics.
+
+            .. versionadded:: 20.0
+        until_date (:class:`datetime.datetime`): Date when restrictions
+           will be lifted for this user.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        can_send_audios (:obj:`bool`): :obj:`True`, if the user is allowed to send audios.
+
+            .. versionadded:: 20.1
+        can_send_documents (:obj:`bool`): :obj:`True`, if the user is allowed to send documents.
+
+            .. versionadded:: 20.1
+        can_send_photos (:obj:`bool`): :obj:`True`, if the user is allowed to send photos.
+
+            .. versionadded:: 20.1
+        can_send_videos (:obj:`bool`): :obj:`True`, if the user is allowed to send videos.
+
+            .. versionadded:: 20.1
+        can_send_video_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send video
+            notes.
+
+            .. versionadded:: 20.1
+        can_send_voice_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send voice
+            notes.
+
+            .. versionadded:: 20.1
+
+    """
+
+    __slots__ = (
+        "can_add_web_page_previews",
+        "can_change_info",
+        "can_invite_users",
+        "can_manage_topics",
+        "can_pin_messages",
+        "can_send_audios",
+        "can_send_documents",
+        "can_send_messages",
+        "can_send_other_messages",
+        "can_send_photos",
+        "can_send_polls",
+        "can_send_video_notes",
+        "can_send_videos",
+        "can_send_voice_notes",
+        "is_member",
+        "until_date",
+    )
+
+    def __init__(
+        self,
+        user: User,
+        is_member: bool,
+        can_change_info: bool,
+        can_invite_users: bool,
+        can_pin_messages: bool,
+        can_send_messages: bool,
+        can_send_polls: bool,
+        can_send_other_messages: bool,
+        can_add_web_page_previews: bool,
+        can_manage_topics: bool,
+        until_date: datetime.datetime,
+        can_send_audios: bool,
+        can_send_documents: bool,
+        can_send_photos: bool,
+        can_send_videos: bool,
+        can_send_video_notes: bool,
+        can_send_voice_notes: bool,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(status=ChatMember.RESTRICTED, user=user, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.is_member: bool = is_member
+            self.can_change_info: bool = can_change_info
+            self.can_invite_users: bool = can_invite_users
+            self.can_pin_messages: bool = can_pin_messages
+            self.can_send_messages: bool = can_send_messages
+            self.can_send_polls: bool = can_send_polls
+            self.can_send_other_messages: bool = can_send_other_messages
+            self.can_add_web_page_previews: bool = can_add_web_page_previews
+            self.can_manage_topics: bool = can_manage_topics
+            self.until_date: datetime.datetime = until_date
+            self.can_send_audios: bool = can_send_audios
+            self.can_send_documents: bool = can_send_documents
+            self.can_send_photos: bool = can_send_photos
+            self.can_send_videos: bool = can_send_videos
+            self.can_send_video_notes: bool = can_send_video_notes
+            self.can_send_voice_notes: bool = can_send_voice_notes
+
+
+class ChatMemberLeft(ChatMember):
+    """
+    Represents a chat member that isn't currently a member of the chat,
+    but may join it themselves.
+
+    .. versionadded:: 13.7
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+
+    Attributes:
+        status (:obj:`str`): The member's status in the chat,
+            always :tg-const:`telegram.ChatMember.LEFT`.
+        user (:class:`telegram.User`): Information about the user.
+    """
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        user: User,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(status=ChatMember.LEFT, user=user, api_kwargs=api_kwargs)
+        self._freeze()
+
+
+class ChatMemberBanned(ChatMember):
+    """
+    Represents a chat member that was banned in the chat and
+    can't return to the chat or view chat messages.
+
+    .. versionadded:: 13.7
+
+    Args:
+        user (:class:`telegram.User`): Information about the user.
+        until_date (:class:`datetime.datetime`): Date when restrictions
+           will be lifted for this user.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+
+    Attributes:
+        status (:obj:`str`): The member's status in the chat,
+            always :tg-const:`telegram.ChatMember.BANNED`.
+        user (:class:`telegram.User`): Information about the user.
+        until_date (:class:`datetime.datetime`): Date when restrictions
+           will be lifted for this user.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+
+    """
+
+    __slots__ = ("until_date",)
+
+    def __init__(
+        self,
+        user: User,
+        until_date: datetime.datetime,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(status=ChatMember.BANNED, user=user, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.until_date: datetime.datetime = until_date

_chatmemberupdated.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChatMemberUpdated."""
+import datetime
+from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+
+from telegram._chat import Chat
+from telegram._chatinvitelink import ChatInviteLink
+from telegram._chatmember import ChatMember
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatMemberUpdated(TelegramObject):
+    """This object represents changes in the status of a chat member.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`chat`, :attr:`from_user`, :attr:`date`,
+    :attr:`old_chat_member` and :attr:`new_chat_member` are equal.
+
+    .. versionadded:: 13.4
+
+    Note:
+        In Python :keyword:`from` is a reserved word. Use :paramref:`from_user` instead.
+
+    Examples:
+        :any:`Chat Member Bot <examples.chatmemberbot>`
+
+    Args:
+        chat (:class:`telegram.Chat`): Chat the user belongs to.
+        from_user (:class:`telegram.User`): Performer of the action, which resulted in the change.
+        date (:class:`datetime.datetime`): Date the change was done in Unix time. Converted to
+            :class:`datetime.datetime`.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        old_chat_member (:class:`telegram.ChatMember`): Previous information about the chat member.
+        new_chat_member (:class:`telegram.ChatMember`): New information about the chat member.
+        invite_link (:class:`telegram.ChatInviteLink`, optional): Chat invite link, which was used
+            by the user to join the chat. For joining by invite link events only.
+        via_chat_folder_invite_link (:obj:`bool`, optional): :obj:`True`, if the user joined the
+            chat via a chat folder invite link
+
+            .. versionadded:: 20.3
+        via_join_request (:obj:`bool`, optional): :obj:`True`, if the user joined the chat after
+            sending a direct join request without using an invite link and being approved by
+            an administrator
+
+            .. versionadded:: 21.2
+
+    Attributes:
+        chat (:class:`telegram.Chat`): Chat the user belongs to.
+        from_user (:class:`telegram.User`): Performer of the action, which resulted in the change.
+        date (:class:`datetime.datetime`): Date the change was done in Unix time. Converted to
+            :class:`datetime.datetime`.
+
+            .. versionchanged:: 20.3
+                |datetime_localization|
+        old_chat_member (:class:`telegram.ChatMember`): Previous information about the chat member.
+        new_chat_member (:class:`telegram.ChatMember`): New information about the chat member.
+        invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link, which was used
+            by the user to join the chat. For joining by invite link events only.
+        via_chat_folder_invite_link (:obj:`bool`): Optional. :obj:`True`, if the user joined the
+            chat via a chat folder invite link
+
+            .. versionadded:: 20.3
+        via_join_request (:obj:`bool`): Optional. :obj:`True`, if the user joined the chat after
+            sending a direct join request without using an invite link and being approved
+            by an administrator
+
+            .. versionadded:: 21.2
+
+    """
+
+    __slots__ = (
+        "chat",
+        "date",
+        "from_user",
+        "invite_link",
+        "new_chat_member",
+        "old_chat_member",
+        "via_chat_folder_invite_link",
+        "via_join_request",
+    )
+
+    def __init__(
+        self,
+        chat: Chat,
+        from_user: User,
+        date: datetime.datetime,
+        old_chat_member: ChatMember,
+        new_chat_member: ChatMember,
+        invite_link: Optional[ChatInviteLink] = None,
+        via_chat_folder_invite_link: Optional[bool] = None,
+        via_join_request: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.chat: Chat = chat
+        self.from_user: User = from_user
+        self.date: datetime.datetime = date
+        self.old_chat_member: ChatMember = old_chat_member
+        self.new_chat_member: ChatMember = new_chat_member
+        self.via_chat_folder_invite_link: Optional[bool] = via_chat_folder_invite_link
+
+        # Optionals
+        self.invite_link: Optional[ChatInviteLink] = invite_link
+        self.via_join_request: Optional[bool] = via_join_request
+
+        self._id_attrs = (
+            self.chat,
+            self.from_user,
+            self.date,
+            self.old_chat_member,
+            self.new_chat_member,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatMemberUpdated"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
+        data["old_chat_member"] = ChatMember.de_json(data.get("old_chat_member"), bot)
+        data["new_chat_member"] = ChatMember.de_json(data.get("new_chat_member"), bot)
+        data["invite_link"] = ChatInviteLink.de_json(data.get("invite_link"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+    def _get_attribute_difference(self, attribute: str) -> Tuple[object, object]:
+        try:
+            old = self.old_chat_member[attribute]
+        except KeyError:
+            old = None
+
+        try:
+            new = self.new_chat_member[attribute]
+        except KeyError:
+            new = None
+
+        return old, new
+
+    def difference(
+        self,
+    ) -> Dict[
+        str,
+        Tuple[
+            Union[str, bool, datetime.datetime, User], Union[str, bool, datetime.datetime, User]
+        ],
+    ]:
+        """Computes the difference between :attr:`old_chat_member` and :attr:`new_chat_member`.
+
+        Example:
+            .. code:: pycon
+
+                >>> chat_member_updated.difference()
+                {'custom_title': ('old title', 'new title')}
+
+        Note:
+            To determine, if the :attr:`telegram.ChatMember.user` attribute has changed, *every*
+            attribute of the user will be checked.
+
+        .. versionadded:: 13.5
+
+        Returns:
+            Dict[:obj:`str`, Tuple[:class:`object`, :class:`object`]]: A dictionary mapping
+            attribute names to tuples of the form ``(old_value, new_value)``
+        """
+        # we first get the names of the attributes that have changed
+        # user.to_dict() is unhashable, so that needs some special casing further down
+        old_dict = self.old_chat_member.to_dict()
+        old_user_dict = old_dict.pop("user")
+        new_dict = self.new_chat_member.to_dict()
+        new_user_dict = new_dict.pop("user")
+
+        # Generator for speed: we only need to iterate over it once
+        # we can't directly use the values from old_dict ^ new_dict b/c that set is unordered
+        attributes = (entry[0] for entry in set(old_dict.items()) ^ set(new_dict.items()))
+
+        result = {attribute: self._get_attribute_difference(attribute) for attribute in attributes}
+        if old_user_dict != new_user_dict:
+            result["user"] = (self.old_chat_member.user, self.new_chat_member.user)
+
+        return result  # type: ignore[return-value]

_chatpermissions.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChatPermission."""
+from typing import TYPE_CHECKING, Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatPermissions(TelegramObject):
+    """Describes actions that a non-administrator user is allowed to take in a chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`can_send_messages`,
+    :attr:`can_send_polls`, :attr:`can_send_other_messages`, :attr:`can_add_web_page_previews`,
+    :attr:`can_change_info`, :attr:`can_invite_users`, :attr:`can_pin_messages`,
+    :attr:`can_send_audios`, :attr:`can_send_documents`, :attr:`can_send_photos`,
+    :attr:`can_send_videos`, :attr:`can_send_video_notes`, :attr:`can_send_voice_notes`, and
+    :attr:`can_manage_topics` are equal.
+
+    .. versionchanged:: 20.0
+        :attr:`can_manage_topics` is considered as well when comparing objects of
+        this type in terms of equality.
+    .. versionchanged:: 20.5
+
+        * :attr:`can_send_audios`, :attr:`can_send_documents`, :attr:`can_send_photos`,
+          :attr:`can_send_videos`, :attr:`can_send_video_notes` and :attr:`can_send_voice_notes`
+          are considered as well when comparing objects of this type in terms of equality.
+        * Removed deprecated argument and attribute ``can_send_media_messages``.
+
+
+    Note:
+        Though not stated explicitly in the official docs, Telegram changes not only the
+        permissions that are set, but also sets all the others to :obj:`False`. However, since not
+        documented, this behavior may change unbeknown to PTB.
+
+    Args:
+        can_send_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send text
+            messages, contacts, locations and venues.
+        can_send_polls (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send polls.
+        can_send_other_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
+            send animations, games, stickers and use inline bots.
+        can_add_web_page_previews (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
+            add web page previews to their messages.
+        can_change_info (:obj:`bool`, optional): :obj:`True`, if the user is allowed to change the
+            chat title, photo and other settings. Ignored in public supergroups.
+        can_invite_users (:obj:`bool`, optional): :obj:`True`, if the user is allowed to invite new
+            users to the chat.
+        can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
+            messages. Ignored in public supergroups.
+        can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to create forum topics. If omitted defaults to the value of
+            :attr:`can_pin_messages`.
+
+            .. versionadded:: 20.0
+        can_send_audios (:obj:`bool`): :obj:`True`, if the user is allowed to send audios.
+
+            .. versionadded:: 20.1
+        can_send_documents (:obj:`bool`): :obj:`True`, if the user is allowed to send documents.
+
+            .. versionadded:: 20.1
+        can_send_photos (:obj:`bool`): :obj:`True`, if the user is allowed to send photos.
+
+            .. versionadded:: 20.1
+        can_send_videos (:obj:`bool`): :obj:`True`, if the user is allowed to send videos.
+
+            .. versionadded:: 20.1
+        can_send_video_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send video
+            notes.
+
+            .. versionadded:: 20.1
+        can_send_voice_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send voice
+            notes.
+
+            .. versionadded:: 20.1
+
+    Attributes:
+        can_send_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send text
+            messages, contacts, locations and venues.
+        can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send polls,
+            implies :attr:`can_send_messages`.
+        can_send_other_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
+            send animations, games, stickers and use inline bots.
+        can_add_web_page_previews (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
+            add web page previews to their messages.
+        can_change_info (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to change the
+            chat title, photo and other settings. Ignored in public supergroups.
+        can_invite_users (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to invite
+            new users to the chat.
+        can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
+            messages. Ignored in public supergroups.
+        can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to create forum topics. If omitted defaults to the value of
+            :attr:`can_pin_messages`.
+
+            .. versionadded:: 20.0
+        can_send_audios (:obj:`bool`): :obj:`True`, if the user is allowed to send audios.
+
+            .. versionadded:: 20.1
+        can_send_documents (:obj:`bool`): :obj:`True`, if the user is allowed to send documents.
+
+            .. versionadded:: 20.1
+        can_send_photos (:obj:`bool`): :obj:`True`, if the user is allowed to send photos.
+
+            .. versionadded:: 20.1
+        can_send_videos (:obj:`bool`): :obj:`True`, if the user is allowed to send videos.
+
+            .. versionadded:: 20.1
+        can_send_video_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send video
+            notes.
+
+            .. versionadded:: 20.1
+        can_send_voice_notes (:obj:`bool`): :obj:`True`, if the user is allowed to send voice
+            notes.
+
+            .. versionadded:: 20.1
+
+    """
+
+    __slots__ = (
+        "can_add_web_page_previews",
+        "can_change_info",
+        "can_invite_users",
+        "can_manage_topics",
+        "can_pin_messages",
+        "can_send_audios",
+        "can_send_documents",
+        "can_send_messages",
+        "can_send_other_messages",
+        "can_send_photos",
+        "can_send_polls",
+        "can_send_video_notes",
+        "can_send_videos",
+        "can_send_voice_notes",
+    )
+
+    def __init__(
+        self,
+        can_send_messages: Optional[bool] = None,
+        can_send_polls: Optional[bool] = None,
+        can_send_other_messages: Optional[bool] = None,
+        can_add_web_page_previews: Optional[bool] = None,
+        can_change_info: Optional[bool] = None,
+        can_invite_users: Optional[bool] = None,
+        can_pin_messages: Optional[bool] = None,
+        can_manage_topics: Optional[bool] = None,
+        can_send_audios: Optional[bool] = None,
+        can_send_documents: Optional[bool] = None,
+        can_send_photos: Optional[bool] = None,
+        can_send_videos: Optional[bool] = None,
+        can_send_video_notes: Optional[bool] = None,
+        can_send_voice_notes: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.can_send_messages: Optional[bool] = can_send_messages
+        self.can_send_polls: Optional[bool] = can_send_polls
+        self.can_send_other_messages: Optional[bool] = can_send_other_messages
+        self.can_add_web_page_previews: Optional[bool] = can_add_web_page_previews
+        self.can_change_info: Optional[bool] = can_change_info
+        self.can_invite_users: Optional[bool] = can_invite_users
+        self.can_pin_messages: Optional[bool] = can_pin_messages
+        self.can_manage_topics: Optional[bool] = can_manage_topics
+        self.can_send_audios: Optional[bool] = can_send_audios
+        self.can_send_documents: Optional[bool] = can_send_documents
+        self.can_send_photos: Optional[bool] = can_send_photos
+        self.can_send_videos: Optional[bool] = can_send_videos
+        self.can_send_video_notes: Optional[bool] = can_send_video_notes
+        self.can_send_voice_notes: Optional[bool] = can_send_voice_notes
+
+        self._id_attrs = (
+            self.can_send_messages,
+            self.can_send_polls,
+            self.can_send_other_messages,
+            self.can_add_web_page_previews,
+            self.can_change_info,
+            self.can_invite_users,
+            self.can_pin_messages,
+            self.can_manage_topics,
+            self.can_send_audios,
+            self.can_send_documents,
+            self.can_send_photos,
+            self.can_send_videos,
+            self.can_send_video_notes,
+            self.can_send_voice_notes,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def all_permissions(cls) -> "ChatPermissions":
+        """
+        This method returns an :class:`ChatPermissions` instance with all attributes
+        set to :obj:`True`. This is e.g. useful when unrestricting a chat member with
+        :meth:`telegram.Bot.restrict_chat_member`.
+
+        .. versionadded:: 20.0
+
+        """
+        return cls(*(14 * (True,)))
+
+    @classmethod
+    def no_permissions(cls) -> "ChatPermissions":
+        """
+        This method returns an :class:`ChatPermissions` instance
+        with all attributes set to :obj:`False`.
+
+        .. versionadded:: 20.0
+        """
+        return cls(*(14 * (False,)))
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChatPermissions"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        api_kwargs = {}
+        # This is a deprecated field that TG still returns for backwards compatibility
+        # Let's filter it out to speed up the de-json process
+        if data.get("can_send_media_messages") is not None:
+            api_kwargs["can_send_media_messages"] = data.pop("can_send_media_messages")
+
+        return super()._de_json(data=data, bot=bot, api_kwargs=api_kwargs)

_choseninlineresult.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python
+# pylint: disable=too-many-arguments
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ChosenInlineResult."""
+
+from typing import TYPE_CHECKING, Optional
+
+from telegram._files.location import Location
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChosenInlineResult(TelegramObject):
+    """
+    Represents a result of an inline query that was chosen by the user and sent to their chat
+    partner.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`result_id` is equal.
+
+    Note:
+        * In Python :keyword:`from` is a reserved word. Use :paramref:`from_user` instead.
+        * It is necessary to enable inline feedback via `@Botfather <https://t.me/BotFather>`_ in
+          order to receive these objects in updates.
+
+    Args:
+        result_id (:obj:`str`): The unique identifier for the result that was chosen.
+        from_user (:class:`telegram.User`): The user that chose the result.
+        location (:class:`telegram.Location`, optional): Sender location, only for bots that
+            require user location.
+        inline_message_id (:obj:`str`, optional): Identifier of the sent inline message. Available
+            only if there is an inline keyboard attached to the message. Will be also received in
+            callback queries and can be used to edit the message.
+        query (:obj:`str`): The query that was used to obtain the result.
+
+    Attributes:
+        result_id (:obj:`str`): The unique identifier for the result that was chosen.
+        from_user (:class:`telegram.User`): The user that chose the result.
+        location (:class:`telegram.Location`): Optional. Sender location, only for bots that
+            require user location.
+        inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message. Available
+            only if there is an inline keyboard attached to the message. Will be also received in
+            callback queries and can be used to edit the message.
+        query (:obj:`str`): The query that was used to obtain the result.
+
+    """
+
+    __slots__ = ("from_user", "inline_message_id", "location", "query", "result_id")
+
+    def __init__(
+        self,
+        result_id: str,
+        from_user: User,
+        query: str,
+        location: Optional[Location] = None,
+        inline_message_id: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        # Required
+        self.result_id: str = result_id
+        self.from_user: User = from_user
+        self.query: str = query
+        # Optionals
+        self.location: Optional[Location] = location
+        self.inline_message_id: Optional[str] = inline_message_id
+
+        self._id_attrs = (self.result_id,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["ChosenInlineResult"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Required
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
+        # Optionals
+        data["location"] = Location.de_json(data.get("location"), bot)
+
+        return super().de_json(data=data, bot=bot)

_dice.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram Dice."""
+from typing import Final, List, Optional
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class Dice(TelegramObject):
+    """
+    This object represents an animated emoji with a random value for currently supported base
+    emoji. (The singular form of "dice" is "die". However, PTB mimics the Telegram API, which uses
+    the term "dice".)
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`value` and :attr:`emoji` are equal.
+
+    Note:
+        If :attr:`emoji` is :tg-const:`telegram.Dice.DARTS`, a value of 6 currently
+        represents a bullseye, while a value of 1 indicates that the dartboard was missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
+
+        If :attr:`emoji` is :tg-const:`telegram.Dice.BASKETBALL`, a value of 4 or 5
+        currently score a basket, while a value of 1 to 3 indicates that the basket was missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
+
+        If :attr:`emoji` is :tg-const:`telegram.Dice.FOOTBALL`, a value of 4 to 5
+        currently scores a goal, while a value of 1 to 3 indicates that the goal was missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
+
+        If :attr:`emoji` is :tg-const:`telegram.Dice.BOWLING`, a value of 6 knocks
+        all the pins, while a value of 1 means all the pins were missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
+
+        If :attr:`emoji` is :tg-const:`telegram.Dice.SLOT_MACHINE`, each value
+        corresponds to a unique combination of symbols, which
+        can be found in our
+        :wiki:`wiki <Code-snippets#map-a-slot-machine-dice-value-to-the-corresponding-symbols>`.
+        However, this behaviour is undocumented and might be changed by Telegram.
+
+    ..
+        In args, some links for limits of `value` intentionally point to constants for only
+        one emoji of a group to avoid duplication. For example, maximum value for Dice, Darts and
+        Bowling is linked to a constant for Bowling.
+
+    Args:
+        value (:obj:`int`): Value of the dice.
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BOWLING`
+            for :tg-const:`telegram.Dice.DICE`, :tg-const:`telegram.Dice.DARTS` and
+            :tg-const:`telegram.Dice.BOWLING` base emoji,
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BASKETBALL`
+            for :tg-const:`telegram.Dice.BASKETBALL` and :tg-const:`telegram.Dice.FOOTBALL`
+            base emoji,
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_SLOT_MACHINE`
+            for :tg-const:`telegram.Dice.SLOT_MACHINE` base emoji.
+        emoji (:obj:`str`): Emoji on which the dice throw animation is based.
+
+    Attributes:
+        value (:obj:`int`): Value of the dice.
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BOWLING`
+            for :tg-const:`telegram.Dice.DICE`, :tg-const:`telegram.Dice.DARTS` and
+            :tg-const:`telegram.Dice.BOWLING` base emoji,
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BASKETBALL`
+            for :tg-const:`telegram.Dice.BASKETBALL` and :tg-const:`telegram.Dice.FOOTBALL`
+            base emoji,
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_SLOT_MACHINE`
+            for :tg-const:`telegram.Dice.SLOT_MACHINE` base emoji.
+        emoji (:obj:`str`): Emoji on which the dice throw animation is based.
+
+    """
+
+    __slots__ = ("emoji", "value")
+
+    def __init__(self, value: int, emoji: str, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.value: int = value
+        self.emoji: str = emoji
+
+        self._id_attrs = (self.value, self.emoji)
+
+        self._freeze()
+
+    DICE: Final[str] = constants.DiceEmoji.DICE
+    """:const:`telegram.constants.DiceEmoji.DICE`"""
+    DARTS: Final[str] = constants.DiceEmoji.DARTS
+    """:const:`telegram.constants.DiceEmoji.DARTS`"""
+    BASKETBALL: Final[str] = constants.DiceEmoji.BASKETBALL
+    """:const:`telegram.constants.DiceEmoji.BASKETBALL`"""
+    FOOTBALL: Final[str] = constants.DiceEmoji.FOOTBALL
+    """:const:`telegram.constants.DiceEmoji.FOOTBALL`"""
+    SLOT_MACHINE: Final[str] = constants.DiceEmoji.SLOT_MACHINE
+    """:const:`telegram.constants.DiceEmoji.SLOT_MACHINE`"""
+    BOWLING: Final[str] = constants.DiceEmoji.BOWLING
+    """
+    :const:`telegram.constants.DiceEmoji.BOWLING`
+
+    .. versionadded:: 13.4
+    """
+    ALL_EMOJI: Final[List[str]] = list(constants.DiceEmoji)
+    """List[:obj:`str`]: A list of all available dice emoji."""
+
+    MIN_VALUE: Final[int] = constants.DiceLimit.MIN_VALUE
+    """:const:`telegram.constants.DiceLimit.MIN_VALUE`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_BOWLING: Final[int] = constants.DiceLimit.MAX_VALUE_BOWLING
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_BOWLING`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_DARTS: Final[int] = constants.DiceLimit.MAX_VALUE_DARTS
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_DARTS`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_DICE: Final[int] = constants.DiceLimit.MAX_VALUE_DICE
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_DICE`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_BASKETBALL: Final[int] = constants.DiceLimit.MAX_VALUE_BASKETBALL
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_BASKETBALL`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_FOOTBALL: Final[int] = constants.DiceLimit.MAX_VALUE_FOOTBALL
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_FOOTBALL`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_SLOT_MACHINE: Final[int] = constants.DiceLimit.MAX_VALUE_SLOT_MACHINE
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_SLOT_MACHINE`
+
+    .. versionadded:: 20.0
+    """

_forcereply.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram ForceReply."""
+
+from typing import Final, Optional
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class ForceReply(TelegramObject):
+    """
+    Upon receiving a message with this object, Telegram clients will display a reply interface to
+    the user (act as if the user has selected the bot's message and tapped 'Reply'). This can be
+    extremely useful if you want to create user-friendly step-by-step interfaces without having
+    to sacrifice `privacy mode <https://core.telegram.org/bots/features#privacy-mode>`_. Not
+    supported in channels and for messages sent on behalf of a Telegram Business account.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`selective` is equal.
+
+    .. versionchanged:: 20.0
+        The (undocumented) argument ``force_reply`` was removed and instead :attr:`force_reply`
+        is now always set to :obj:`True` as expected by the Bot API.
+
+    Args:
+        selective (:obj:`bool`, optional): Use this parameter if you want to force reply from
+            specific users only. Targets:
+
+            1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the
+               :class:`telegram.Message` object.
+            2) If the bot's message is a reply to a message in the same chat and forum topic,
+               sender of the original message.
+
+        input_field_placeholder (:obj:`str`, optional): The placeholder to be shown in the input
+            field when the reply is active;
+            :tg-const:`telegram.ForceReply.MIN_INPUT_FIELD_PLACEHOLDER`-
+            :tg-const:`telegram.ForceReply.MAX_INPUT_FIELD_PLACEHOLDER`
+            characters.
+
+            .. versionadded:: 13.7
+
+    Attributes:
+        force_reply (:obj:`True`): Shows reply interface to the user, as if they manually selected
+            the bots message and tapped 'Reply'.
+        selective (:obj:`bool`): Optional. Force reply from specific users only. Targets:
+
+            1) Users that are @mentioned in the :attr:`~telegram.Message.text` of the
+               :class:`telegram.Message` object.
+            2) If the bot's message is a reply to a message in the same chat and forum topic,
+                sender of the original message.
+        input_field_placeholder (:obj:`str`): Optional. The placeholder to be shown in the input
+            field when the reply is active;
+            :tg-const:`telegram.ForceReply.MIN_INPUT_FIELD_PLACEHOLDER`-
+            :tg-const:`telegram.ForceReply.MAX_INPUT_FIELD_PLACEHOLDER`
+            characters.
+
+            .. versionadded:: 13.7
+
+    """
+
+    __slots__ = ("force_reply", "input_field_placeholder", "selective")
+
+    def __init__(
+        self,
+        selective: Optional[bool] = None,
+        input_field_placeholder: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.force_reply: bool = True
+        self.selective: Optional[bool] = selective
+        self.input_field_placeholder: Optional[str] = input_field_placeholder
+
+        self._id_attrs = (self.selective,)
+
+        self._freeze()
+
+    MIN_INPUT_FIELD_PLACEHOLDER: Final[int] = constants.ReplyLimit.MIN_INPUT_FIELD_PLACEHOLDER
+    """:const:`telegram.constants.ReplyLimit.MIN_INPUT_FIELD_PLACEHOLDER`
+
+    .. versionadded:: 20.0
+    """
+    MAX_INPUT_FIELD_PLACEHOLDER: Final[int] = constants.ReplyLimit.MAX_INPUT_FIELD_PLACEHOLDER
+    """:const:`telegram.constants.ReplyLimit.MAX_INPUT_FIELD_PLACEHOLDER`
+
+    .. versionadded:: 20.0
+    """

_forumtopic.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains objects related to Telegram forum topics."""
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class ForumTopic(TelegramObject):
+    """
+    This object represents a forum topic.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`message_thread_id`, :attr:`name` and :attr:`icon_color`
+    are equal.
+
+    .. versionadded:: 20.0
+
+    Args:
+        message_thread_id (:obj:`int`): Unique identifier of the forum topic
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`, optional): Unique identifier of the custom emoji shown
+            as the topic icon.
+
+    Attributes:
+        message_thread_id (:obj:`int`): Unique identifier of the forum topic
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji shown
+            as the topic icon.
+    """
+
+    __slots__ = ("icon_color", "icon_custom_emoji_id", "message_thread_id", "name")
+
+    def __init__(
+        self,
+        message_thread_id: int,
+        name: str,
+        icon_color: int,
+        icon_custom_emoji_id: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.message_thread_id: int = message_thread_id
+        self.name: str = name
+        self.icon_color: int = icon_color
+        self.icon_custom_emoji_id: Optional[str] = icon_custom_emoji_id
+
+        self._id_attrs = (self.message_thread_id, self.name, self.icon_color)
+
+        self._freeze()
+
+
+class ForumTopicCreated(TelegramObject):
+    """
+    This object represents the content of a service message about a new forum topic created in
+    the chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`name` and :attr:`icon_color` are equal.
+
+    .. versionadded:: 20.0
+
+    Args:
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`, optional): Unique identifier of the custom emoji shown
+            as the topic icon.
+
+    Attributes:
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji shown
+            as the topic icon.
+    """
+
+    __slots__ = ("icon_color", "icon_custom_emoji_id", "name")
+
+    def __init__(
+        self,
+        name: str,
+        icon_color: int,
+        icon_custom_emoji_id: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.name: str = name
+        self.icon_color: int = icon_color
+        self.icon_custom_emoji_id: Optional[str] = icon_custom_emoji_id
+
+        self._id_attrs = (self.name, self.icon_color)
+
+        self._freeze()
+
+
+class ForumTopicClosed(TelegramObject):
+    """
+    This object represents a service message about a forum topic closed in the chat.
+    Currently holds no information.
+
+    .. versionadded:: 20.0
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None) -> None:
+        super().__init__(api_kwargs=api_kwargs)
+
+        self._freeze()
+
+
+class ForumTopicReopened(TelegramObject):
+    """
+    This object represents a service message about a forum topic reopened in the chat.
+    Currently holds no information.
+
+    .. versionadded:: 20.0
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None) -> None:
+        super().__init__(api_kwargs=api_kwargs)
+
+        self._freeze()
+
+
+class ForumTopicEdited(TelegramObject):
+    """
+    This object represents a service message about an edited forum topic.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`name` and :attr:`icon_custom_emoji_id` are equal.
+
+    .. versionadded:: 20.0
+
+    Args:
+        name (:obj:`str`, optional): New name of the topic, if it was edited.
+        icon_custom_emoji_id (:obj:`str`, optional): New identifier of the custom emoji shown as
+            the topic icon, if it was edited; an empty string if the icon was removed.
+
+    Attributes:
+        name (:obj:`str`): Optional. New name of the topic, if it was edited.
+        icon_custom_emoji_id (:obj:`str`): Optional. New identifier of the custom emoji shown as
+            the topic icon, if it was edited; an empty string if the icon was removed.
+    """
+
+    __slots__ = ("icon_custom_emoji_id", "name")
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        icon_custom_emoji_id: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.name: Optional[str] = name
+        self.icon_custom_emoji_id: Optional[str] = icon_custom_emoji_id
+
+        self._id_attrs = (self.name, self.icon_custom_emoji_id)
+
+        self._freeze()
+
+
+class GeneralForumTopicHidden(TelegramObject):
+    """
+    This object represents a service message about General forum topic hidden in the chat.
+    Currently holds no information.
+
+    .. versionadded:: 20.0
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self._freeze()
+
+
+class GeneralForumTopicUnhidden(TelegramObject):
+    """
+    This object represents a service message about General forum topic unhidden in the chat.
+    Currently holds no information.
+
+    .. versionadded:: 20.0
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self._freeze()

_giveaway.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an objects that are related to Telegram giveaways."""
+import datetime
+from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+
+from telegram._chat import Chat
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot, Message
+
+
+class Giveaway(TelegramObject):
+    """This object represents a message about a scheduled giveaway.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`chats`, :attr:`winners_selection_date` and
+    :attr:`winner_count` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        chats (Tuple[:class:`telegram.Chat`]): The list of chats which the user must join to
+            participate in the giveaway.
+        winners_selection_date (:class:`datetime.datetime`): The date when the giveaway winner will
+            be selected. |datetime_localization|
+        winner_count (:obj:`int`): The number of users which are supposed to be selected as winners
+            of the giveaway.
+        only_new_members (:obj:`True`, optional): If :obj:`True`, only users who join the chats
+            after the giveaway started should be eligible to win.
+        has_public_winners (:obj:`True`, optional): :obj:`True`, if the list of giveaway winners
+            will be visible to everyone
+        prize_description (:obj:`str`, optional): Description of additional giveaway prize
+        country_codes (Sequence[:obj:`str`]): A list of two-letter ISO 3166-1 alpha-2
+            country codes indicating the countries from which eligible users for the giveaway must
+            come. If empty, then all users can participate in the giveaway. Users with a phone
+            number that was bought on Fragment can always participate in giveaways.
+        premium_subscription_month_count (:obj:`int`, optional): The number of months the Telegram
+            Premium subscription won from the giveaway will be active for.
+
+    Attributes:
+        chats (Sequence[:class:`telegram.Chat`]): The list of chats which the user must join to
+            participate in the giveaway.
+        winners_selection_date (:class:`datetime.datetime`): The date when the giveaway winner will
+            be selected. |datetime_localization|
+        winner_count (:obj:`int`): The number of users which are supposed to be selected as winners
+            of the giveaway.
+        only_new_members (:obj:`True`): Optional. If :obj:`True`, only users who join the chats
+            after the giveaway started should be eligible to win.
+        has_public_winners (:obj:`True`): Optional. :obj:`True`, if the list of giveaway winners
+            will be visible to everyone
+        prize_description (:obj:`str`): Optional. Description of additional giveaway prize
+        country_codes (Tuple[:obj:`str`]): Optional. A tuple of two-letter ISO 3166-1 alpha-2
+            country codes indicating the countries from which eligible users for the giveaway must
+            come. If empty, then all users can participate in the giveaway. Users with a phone
+            number that was bought on Fragment can always participate in giveaways.
+        premium_subscription_month_count (:obj:`int`): Optional. The number of months the Telegram
+            Premium subscription won from the giveaway will be active for.
+    """
+
+    __slots__ = (
+        "chats",
+        "country_codes",
+        "has_public_winners",
+        "only_new_members",
+        "premium_subscription_month_count",
+        "prize_description",
+        "winner_count",
+        "winners_selection_date",
+    )
+
+    def __init__(
+        self,
+        chats: Sequence[Chat],
+        winners_selection_date: datetime.datetime,
+        winner_count: int,
+        only_new_members: Optional[bool] = None,
+        has_public_winners: Optional[bool] = None,
+        prize_description: Optional[str] = None,
+        country_codes: Optional[Sequence[str]] = None,
+        premium_subscription_month_count: Optional[int] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.chats: Tuple[Chat, ...] = tuple(chats)
+        self.winners_selection_date: datetime.datetime = winners_selection_date
+        self.winner_count: int = winner_count
+        self.only_new_members: Optional[bool] = only_new_members
+        self.has_public_winners: Optional[bool] = has_public_winners
+        self.prize_description: Optional[str] = prize_description
+        self.country_codes: Tuple[str, ...] = parse_sequence_arg(country_codes)
+        self.premium_subscription_month_count: Optional[int] = premium_subscription_month_count
+
+        self._id_attrs = (
+            self.chats,
+            self.winners_selection_date,
+            self.winner_count,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["Giveaway"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if data is None:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["chats"] = tuple(Chat.de_list(data.get("chats"), bot))
+        data["winners_selection_date"] = from_timestamp(
+            data.get("winners_selection_date"), tzinfo=loc_tzinfo
+        )
+
+        return super().de_json(data=data, bot=bot)
+
+
+class GiveawayCreated(TelegramObject):
+    """This object represents a service message about the creation of a scheduled giveaway.
+    Currently holds no information.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self._freeze()
+
+
+class GiveawayWinners(TelegramObject):
+    """This object represents a message about the completion of a giveaway with public winners.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`chat`, :attr:`giveaway_message_id`,
+    :attr:`winners_selection_date`, :attr:`winner_count` and :attr:`winners` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        chat (:class:`telegram.Chat`): The chat that created the giveaway
+        giveaway_message_id (:obj:`int`): Identifier of the message with the giveaway in the chat
+        winners_selection_date (:class:`datetime.datetime`): Point in time when winners of the
+            giveaway were selected. |datetime_localization|
+        winner_count (:obj:`int`): Total number of winners in the giveaway
+        winners	(Sequence[:class:`telegram.User`]): List of up to
+            :tg-const:`telegram.constants.GiveawayLimit.MAX_WINNERS` winners of the giveaway
+        additional_chat_count (:obj:`int`, optional): The number of other chats the user had to
+            join in order to be eligible for the giveaway
+        premium_subscription_month_count (:obj:`int`, optional): The number of months the Telegram
+            Premium subscription won from the giveaway will be active for
+        unclaimed_prize_count (:obj:`int`, optional): Number of undistributed prizes
+        only_new_members (:obj:`True`, optional): :obj:`True`, if only users who had joined the
+            chats after the giveaway started were eligible to win
+        was_refunded (:obj:`True`, optional): :obj:`True`, if the giveaway was canceled because the
+            payment for it was refunded
+        prize_description (:obj:`str`, optional): Description of additional giveaway prize
+
+    Attributes:
+        chat (:class:`telegram.Chat`): The chat that created the giveaway
+        giveaway_message_id (:obj:`int`): Identifier of the message with the giveaway in the chat
+        winners_selection_date (:class:`datetime.datetime`): Point in time when winners of the
+            giveaway were selected. |datetime_localization|
+        winner_count (:obj:`int`): Total number of winners in the giveaway
+        winners	(Tuple[:class:`telegram.User`]): tuple of up to
+            :tg-const:`telegram.constants.GiveawayLimit.MAX_WINNERS` winners of the giveaway
+        additional_chat_count (:obj:`int`): Optional. The number of other chats the user had to
+            join in order to be eligible for the giveaway
+        premium_subscription_month_count (:obj:`int`): Optional. The number of months the Telegram
+            Premium subscription won from the giveaway will be active for
+        unclaimed_prize_count (:obj:`int`): Optional. Number of undistributed prizes
+        only_new_members (:obj:`True`): Optional. :obj:`True`, if only users who had joined the
+            chats after the giveaway started were eligible to win
+        was_refunded (:obj:`True`): Optional. :obj:`True`, if the giveaway was canceled because the
+            payment for it was refunded
+        prize_description (:obj:`str`): Optional. Description of additional giveaway prize
+    """
+
+    __slots__ = (
+        "additional_chat_count",
+        "chat",
+        "giveaway_message_id",
+        "only_new_members",
+        "premium_subscription_month_count",
+        "prize_description",
+        "unclaimed_prize_count",
+        "was_refunded",
+        "winner_count",
+        "winners",
+        "winners_selection_date",
+    )
+
+    def __init__(
+        self,
+        chat: Chat,
+        giveaway_message_id: int,
+        winners_selection_date: datetime.datetime,
+        winner_count: int,
+        winners: Sequence[User],
+        additional_chat_count: Optional[int] = None,
+        premium_subscription_month_count: Optional[int] = None,
+        unclaimed_prize_count: Optional[int] = None,
+        only_new_members: Optional[bool] = None,
+        was_refunded: Optional[bool] = None,
+        prize_description: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.chat: Chat = chat
+        self.giveaway_message_id: int = giveaway_message_id
+        self.winners_selection_date: datetime.datetime = winners_selection_date
+        self.winner_count: int = winner_count
+        self.winners: Tuple[User, ...] = tuple(winners)
+        self.additional_chat_count: Optional[int] = additional_chat_count
+        self.premium_subscription_month_count: Optional[int] = premium_subscription_month_count
+        self.unclaimed_prize_count: Optional[int] = unclaimed_prize_count
+        self.only_new_members: Optional[bool] = only_new_members
+        self.was_refunded: Optional[bool] = was_refunded
+        self.prize_description: Optional[str] = prize_description
+
+        self._id_attrs = (
+            self.chat,
+            self.giveaway_message_id,
+            self.winners_selection_date,
+            self.winner_count,
+            self.winners,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["GiveawayWinners"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if data is None:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["winners"] = tuple(User.de_list(data.get("winners"), bot))
+        data["winners_selection_date"] = from_timestamp(
+            data.get("winners_selection_date"), tzinfo=loc_tzinfo
+        )
+
+        return super().de_json(data=data, bot=bot)
+
+
+class GiveawayCompleted(TelegramObject):
+    """This object represents a service message about the completion of a giveaway without public
+    winners.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`winner_count` and :attr:`unclaimed_prize_count` are equal.
+
+    .. versionadded:: 20.8
+
+
+    Args:
+        winner_count (:obj:`int`): Number of winners in the giveaway
+        unclaimed_prize_count (:obj:`int`, optional): Number of undistributed prizes
+        giveaway_message (:class:`telegram.Message`, optional): Message with the giveaway that was
+            completed, if it wasn't deleted
+
+    Attributes:
+        winner_count (:obj:`int`): Number of winners in the giveaway
+        unclaimed_prize_count (:obj:`int`): Optional. Number of undistributed prizes
+        giveaway_message (:class:`telegram.Message`): Optional. Message with the giveaway that was
+            completed, if it wasn't deleted
+    """
+
+    __slots__ = ("giveaway_message", "unclaimed_prize_count", "winner_count")
+
+    def __init__(
+        self,
+        winner_count: int,
+        unclaimed_prize_count: Optional[int] = None,
+        giveaway_message: Optional["Message"] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        self.winner_count: int = winner_count
+        self.unclaimed_prize_count: Optional[int] = unclaimed_prize_count
+        self.giveaway_message: Optional[Message] = giveaway_message
+
+        self._id_attrs = (
+            self.winner_count,
+            self.unclaimed_prize_count,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["GiveawayCompleted"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if data is None:
+            return None
+
+        # Unfortunately, this needs to be here due to cyclic imports
+        from telegram._message import Message  # pylint: disable=import-outside-toplevel
+
+        data["giveaway_message"] = Message.de_json(data.get("giveaway_message"), bot)
+
+        return super().de_json(data=data, bot=bot)

_keyboardbutton.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram KeyboardButton."""
+
+from typing import TYPE_CHECKING, Optional
+
+from telegram._keyboardbuttonpolltype import KeyboardButtonPollType
+from telegram._keyboardbuttonrequest import KeyboardButtonRequestChat, KeyboardButtonRequestUsers
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+from telegram._webappinfo import WebAppInfo
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class KeyboardButton(TelegramObject):
+    """
+    This object represents one button of the reply keyboard. At most one of the optional fields
+    must be used to specify type of the button. For simple text buttons, :obj:`str`
+    can be used instead of this object to specify text of the button.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`text`, :attr:`request_contact`, :attr:`request_location`,
+    :attr:`request_poll`, :attr:`web_app`, :attr:`request_users` and :attr:`request_chat` are
+    equal.
+
+    Note:
+        * Optional fields are mutually exclusive.
+        * :attr:`request_contact` and :attr:`request_location` options will only work in Telegram
+          versions released after 9 April, 2016. Older clients will display unsupported message.
+        * :attr:`request_poll` option will only work in Telegram versions released after 23
+          January, 2020. Older clients will display unsupported message.
+        * :attr:`web_app` option will only work in Telegram versions released after 16 April, 2022.
+          Older clients will display unsupported message.
+        * :attr:`request_users` and :attr:`request_chat` options will only work in Telegram
+          versions released after 3 February, 2023. Older clients will display unsupported
+          message.
+
+    .. versionchanged:: 21.0
+       Removed deprecated argument and attribute ``request_user``.
+    .. versionchanged:: 20.0
+       :attr:`web_app` is considered as well when comparing objects of this type in terms of
+       equality.
+    .. versionchanged:: 20.5
+       :attr:`request_users` and :attr:`request_chat` are considered as well when
+       comparing objects of this type in terms of equality.
+
+    Args:
+        text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be
+            sent to the bot as a message when the button is pressed.
+        request_contact (:obj:`bool`, optional): If :obj:`True`, the user's phone number will be
+            sent as a contact when the button is pressed. Available in private chats only.
+        request_location (:obj:`bool`, optional): If :obj:`True`, the user's current location will
+            be sent when the button is pressed. Available in private chats only.
+        request_poll (:class:`~telegram.KeyboardButtonPollType`, optional): If specified, the user
+            will be asked to create a poll and send it to the bot when the button is pressed.
+            Available in private chats only.
+        web_app (:class:`~telegram.WebAppInfo`, optional): If specified, the described `Web App
+            <https://core.telegram.org/bots/webapps>`_ will be launched when the button is pressed.
+            The Web App will be able to send a :attr:`Message.web_app_data` service message.
+            Available in private chats only.
+
+            .. versionadded:: 20.0
+
+        request_users (:class:`KeyboardButtonRequestUsers`, optional): If specified, pressing the
+            button will open a list of suitable users. Tapping on any user will send its
+            identifier to the bot in a :attr:`telegram.Message.users_shared` service message.
+            Available in private chats only.
+
+            .. versionadded:: 20.8
+        request_chat (:class:`KeyboardButtonRequestChat`, optional): If specified, pressing the
+            button will open a list of suitable chats. Tapping on a chat will send its
+            identifier to the bot in a :attr:`telegram.Message.chat_shared` service message.
+            Available in private chats only.
+
+            .. versionadded:: 20.1
+    Attributes:
+        text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be
+            sent to the bot as a message when the button is pressed.
+        request_contact (:obj:`bool`): Optional. If :obj:`True`, the user's phone number will be
+            sent as a contact when the button is pressed. Available in private chats only.
+        request_location (:obj:`bool`): Optional. If :obj:`True`, the user's current location will
+            be sent when the button is pressed. Available in private chats only.
+        request_poll (:class:`~telegram.KeyboardButtonPollType`): Optional. If specified,
+            the user will be asked to create a poll and send it to the bot when the button is
+            pressed. Available in private chats only.
+        web_app (:class:`~telegram.WebAppInfo`): Optional. If specified, the described `Web App
+            <https://core.telegram.org/bots/webapps>`_ will be launched when the button is pressed.
+            The Web App will be able to send a :attr:`Message.web_app_data` service message.
+            Available in private chats only.
+
+            .. versionadded:: 20.0
+        request_users (:class:`KeyboardButtonRequestUsers`): Optional. If specified, pressing the
+            button will open a list of suitable users. Tapping on any user will send its
+            identifier to the bot in a :attr:`telegram.Message.users_shared` service message.
+            Available in private chats only.
+
+            .. versionadded:: 20.8
+        request_chat (:class:`KeyboardButtonRequestChat`): Optional. If specified, pressing the
+            button will open a list of suitable chats. Tapping on a chat will send its
+            identifier to the bot in a :attr:`telegram.Message.chat_shared` service message.
+            Available in private chats only.
+
+            .. versionadded:: 20.1
+    """
+
+    __slots__ = (
+        "request_chat",
+        "request_contact",
+        "request_location",
+        "request_poll",
+        "request_users",
+        "text",
+        "web_app",
+    )
+
+    def __init__(
+        self,
+        text: str,
+        request_contact: Optional[bool] = None,
+        request_location: Optional[bool] = None,
+        request_poll: Optional[KeyboardButtonPollType] = None,
+        web_app: Optional[WebAppInfo] = None,
+        request_chat: Optional[KeyboardButtonRequestChat] = None,
+        request_users: Optional[KeyboardButtonRequestUsers] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        # Required
+        self.text: str = text
+        # Optionals
+        self.request_contact: Optional[bool] = request_contact
+        self.request_location: Optional[bool] = request_location
+        self.request_poll: Optional[KeyboardButtonPollType] = request_poll
+        self.web_app: Optional[WebAppInfo] = web_app
+        self.request_users: Optional[KeyboardButtonRequestUsers] = request_users
+        self.request_chat: Optional[KeyboardButtonRequestChat] = request_chat
+
+        self._id_attrs = (
+            self.text,
+            self.request_contact,
+            self.request_location,
+            self.request_poll,
+            self.web_app,
+            self.request_users,
+            self.request_chat,
+        )
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["KeyboardButton"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["request_poll"] = KeyboardButtonPollType.de_json(data.get("request_poll"), bot)
+        data["request_users"] = KeyboardButtonRequestUsers.de_json(data.get("request_users"), bot)
+        data["request_chat"] = KeyboardButtonRequestChat.de_json(data.get("request_chat"), bot)
+        data["web_app"] = WebAppInfo.de_json(data.get("web_app"), bot)
+
+        api_kwargs = {}
+        # This is a deprecated field that TG still returns for backwards compatibility
+        # Let's filter it out to speed up the de-json process
+        if request_user := data.get("request_user"):
+            api_kwargs = {"request_user": request_user}
+
+        return super()._de_json(data=data, bot=bot, api_kwargs=api_kwargs)

_keyboardbuttonpolltype.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a type of a Telegram Poll."""
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils import enum
+from telegram._utils.types import JSONDict
+from telegram.constants import PollType
+
+
+class KeyboardButtonPollType(TelegramObject):
+    """This object represents type of a poll, which is allowed to be created
+    and sent when the corresponding button is pressed.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal.
+
+    Examples:
+        :any:`Poll Bot <examples.pollbot>`
+
+    Args:
+        type (:obj:`str`, optional): If :tg-const:`telegram.Poll.QUIZ` is passed, the user will be
+            allowed to create only polls in the quiz mode. If :tg-const:`telegram.Poll.REGULAR` is
+            passed, only regular polls will be allowed. Otherwise, the user will be allowed to
+            create a poll of any type.
+    Attributes:
+        type (:obj:`str`): Optional. If equals :tg-const:`telegram.Poll.QUIZ`, the user will
+            be allowed to create only polls in the quiz mode. If equals
+            :tg-const:`telegram.Poll.REGULAR`, only regular polls will be allowed.
+            Otherwise, the user will be allowed to create a poll of any type.
+    """
+
+    __slots__ = ("type",)
+
+    def __init__(
+        self,
+        type: Optional[str] = None,  # pylint: disable=redefined-builtin
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.type: Optional[str] = enum.get_member(PollType, type, type)
+
+        self._id_attrs = (self.type,)
+
+        self._freeze()

_keyboardbuttonrequest.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains two objects to request chats/users."""
+
+from typing import TYPE_CHECKING, Optional
+
+from telegram._chatadministratorrights import ChatAdministratorRights
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class KeyboardButtonRequestUsers(TelegramObject):
+    """This object defines the criteria used to request a suitable user. The identifier of the
+    selected user will be shared with the bot when the corresponding button is pressed. `More
+    about requesting users » <https://core.telegram.org/bots/features#chat-and-user-selection>`_.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`request_id` is equal.
+
+    .. versionadded:: 20.8
+        This class was previously named ``KeyboardButtonRequestUser``.
+
+    Args:
+        request_id (:obj:`int`): Signed 32-bit identifier of the request, which will be received
+            back in the :class:`telegram.UsersShared` object. Must be unique within the message.
+        user_is_bot (:obj:`bool`, optional): Pass :obj:`True` to request a bot, pass :obj:`False`
+            to request a regular user. If not specified, no additional restrictions are applied.
+        user_is_premium (:obj:`bool`, optional): Pass :obj:`True` to request a premium user, pass
+            :obj:`False` to request a non-premium user. If not specified, no additional
+            restrictions are applied.
+        max_quantity (:obj:`int`, optional): The maximum number of users to be selected;
+            :tg-const:`telegram.constants.KeyboardButtonRequestUsersLimit.MIN_QUANTITY` -
+            :tg-const:`telegram.constants.KeyboardButtonRequestUsersLimit.MAX_QUANTITY`.
+            Defaults to :tg-const:`telegram.constants.KeyboardButtonRequestUsersLimit.MIN_QUANTITY`
+            .
+
+            .. versionadded:: 20.8
+        request_name (:obj:`bool`, optional): Pass :obj:`True` to request the users' first and last
+            name.
+
+            .. versionadded:: 21.1
+        request_username (:obj:`bool`, optional): Pass :obj:`True` to request the users' username.
+
+            .. versionadded:: 21.1
+        request_photo (:obj:`bool`, optional): Pass :obj:`True` to request the users' photo.
+
+            .. versionadded:: 21.1
+
+    Attributes:
+        request_id (:obj:`int`): Identifier of the request.
+        user_is_bot (:obj:`bool`): Optional. Pass :obj:`True` to request a bot, pass :obj:`False`
+            to request a regular user. If not specified, no additional restrictions are applied.
+        user_is_premium (:obj:`bool`): Optional. Pass :obj:`True` to request a premium user, pass
+            :obj:`False` to request a non-premium user. If not specified, no additional
+            restrictions are applied.
+        max_quantity (:obj:`int`): Optional. The maximum number of users to be selected;
+            :tg-const:`telegram.constants.KeyboardButtonRequestUsersLimit.MIN_QUANTITY` -
+            :tg-const:`telegram.constants.KeyboardButtonRequestUsersLimit.MAX_QUANTITY`.
+            Defaults to :tg-const:`telegram.constants.KeyboardButtonRequestUsersLimit.MIN_QUANTITY`
+            .
+
+            .. versionadded:: 20.8
+        request_name (:obj:`bool`): Optional. Pass :obj:`True` to request the users' first and last
+            name.
+
+            .. versionadded:: 21.1
+        request_username (:obj:`bool`): Optional. Pass :obj:`True` to request the users' username.
+
+            .. versionadded:: 21.1
+        request_photo (:obj:`bool`): Optional. Pass :obj:`True` to request the users' photo.
+
+            .. versionadded:: 21.1
+
+    """
+
+    __slots__ = (
+        "max_quantity",
+        "request_id",
+        "request_name",
+        "request_photo",
+        "request_username",
+        "user_is_bot",
+        "user_is_premium",
+    )
+
+    def __init__(
+        self,
+        request_id: int,
+        user_is_bot: Optional[bool] = None,
+        user_is_premium: Optional[bool] = None,
+        max_quantity: Optional[int] = None,
+        request_name: Optional[bool] = None,
+        request_username: Optional[bool] = None,
+        request_photo: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.request_id: int = request_id
+
+        # Optionals
+        self.user_is_bot: Optional[bool] = user_is_bot
+        self.user_is_premium: Optional[bool] = user_is_premium
+        self.max_quantity: Optional[int] = max_quantity
+        self.request_name: Optional[bool] = request_name
+        self.request_username: Optional[bool] = request_username
+        self.request_photo: Optional[bool] = request_photo
+
+        self._id_attrs = (self.request_id,)
+
+        self._freeze()
+
+
+class KeyboardButtonRequestChat(TelegramObject):
+    """This object defines the criteria used to request a suitable chat. The identifier of the
+    selected user will be shared with the bot when the corresponding button is pressed. `More
+    about requesting users » <https://core.telegram.org/bots/features#chat-and-user-selection>`_.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`request_id` is equal.
+
+    .. versionadded:: 20.1
+
+    Args:
+        request_id (:obj:`int`): Signed 32-bit identifier of the request, which will be received
+            back in the :class:`telegram.ChatShared` object. Must be unique within the message.
+        chat_is_channel (:obj:`bool`): Pass :obj:`True` to request a channel chat, pass
+            :obj:`False` to request a group or a supergroup chat.
+        chat_is_forum (:obj:`bool`, optional): Pass :obj:`True` to request a forum supergroup, pass
+            :obj:`False` to request a non-forum chat. If not specified, no additional
+            restrictions are applied.
+        chat_has_username (:obj:`bool`, optional): Pass :obj:`True` to request a supergroup or a
+            channel with a username, pass :obj:`False` to request a chat without a username. If
+            not specified, no additional restrictions are applied.
+        chat_is_created (:obj:`bool`, optional): Pass :obj:`True` to request a chat owned by the
+            user. Otherwise, no additional restrictions are applied.
+        user_administrator_rights (:class:`ChatAdministratorRights`, optional): Specifies the
+            required administrator rights of the user in the chat. If not specified, no additional
+            restrictions are applied.
+        bot_administrator_rights (:class:`ChatAdministratorRights`, optional): Specifies the
+            required administrator rights of the bot in the chat. The rights must be a subset of
+            :paramref:`user_administrator_rights`. If not specified, no additional restrictions are
+            applied.
+        bot_is_member (:obj:`bool`, optional): Pass :obj:`True` to request a chat with the bot
+            as a member. Otherwise, no additional restrictions are applied.
+        request_title (:obj:`bool`, optional): Pass :obj:`True` to request the chat's title.
+
+            .. versionadded:: 21.1
+        request_username (:obj:`bool`, optional): Pass :obj:`True` to request the chat's username.
+
+            .. versionadded:: 21.1
+        request_photo (:obj:`bool`, optional): Pass :obj:`True` to request the chat's photo.
+
+            .. versionadded:: 21.1
+    Attributes:
+        request_id (:obj:`int`): Identifier of the request.
+        chat_is_channel (:obj:`bool`): Pass :obj:`True` to request a channel chat, pass
+            :obj:`False` to request a group or a supergroup chat.
+        chat_is_forum (:obj:`bool`): Optional. Pass :obj:`True` to request a forum supergroup, pass
+            :obj:`False` to request a non-forum chat. If not specified, no additional
+            restrictions are applied.
+        chat_has_username (:obj:`bool`): Optional. Pass :obj:`True` to request a supergroup or a
+            channel with a username, pass :obj:`False` to request a chat without a username. If
+            not specified, no additional restrictions are applied.
+        chat_is_created (:obj:`bool`) Optional. Pass :obj:`True` to request a chat owned by the
+            user. Otherwise, no additional restrictions are applied.
+        user_administrator_rights (:class:`ChatAdministratorRights`) Optional. Specifies the
+            required administrator rights of the user in the chat. If not specified, no additional
+            restrictions are applied.
+        bot_administrator_rights (:class:`ChatAdministratorRights`) Optional. Specifies the
+            required administrator rights of the bot in the chat. The rights must be a subset of
+            :attr:`user_administrator_rights`. If not specified, no additional restrictions are
+            applied.
+        bot_is_member (:obj:`bool`) Optional. Pass :obj:`True` to request a chat with the bot
+            as a member. Otherwise, no additional restrictions are applied.
+        request_title (:obj:`bool`): Optional. Pass :obj:`True` to request the chat's title.
+
+            .. versionadded:: 21.1
+        request_username (:obj:`bool`): Optional. Pass :obj:`True` to request the chat's username.
+
+            .. versionadded:: 21.1
+        request_photo (:obj:`bool`): Optional. Pass :obj:`True` to request the chat's photo.
+
+            .. versionadded:: 21.1
+    """
+
+    __slots__ = (
+        "bot_administrator_rights",
+        "bot_is_member",
+        "chat_has_username",
+        "chat_is_channel",
+        "chat_is_created",
+        "chat_is_forum",
+        "request_id",
+        "request_photo",
+        "request_title",
+        "request_username",
+        "user_administrator_rights",
+    )
+
+    def __init__(
+        self,
+        request_id: int,
+        chat_is_channel: bool,
+        chat_is_forum: Optional[bool] = None,
+        chat_has_username: Optional[bool] = None,
+        chat_is_created: Optional[bool] = None,
+        user_administrator_rights: Optional[ChatAdministratorRights] = None,
+        bot_administrator_rights: Optional[ChatAdministratorRights] = None,
+        bot_is_member: Optional[bool] = None,
+        request_title: Optional[bool] = None,
+        request_username: Optional[bool] = None,
+        request_photo: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # required
+        self.request_id: int = request_id
+        self.chat_is_channel: bool = chat_is_channel
+
+        # optional
+        self.chat_is_forum: Optional[bool] = chat_is_forum
+        self.chat_has_username: Optional[bool] = chat_has_username
+        self.chat_is_created: Optional[bool] = chat_is_created
+        self.user_administrator_rights: Optional[ChatAdministratorRights] = (
+            user_administrator_rights
+        )
+        self.bot_administrator_rights: Optional[ChatAdministratorRights] = bot_administrator_rights
+        self.bot_is_member: Optional[bool] = bot_is_member
+        self.request_title: Optional[bool] = request_title
+        self.request_username: Optional[bool] = request_username
+        self.request_photo: Optional[bool] = request_photo
+
+        self._id_attrs = (self.request_id,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["KeyboardButtonRequestChat"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["user_administrator_rights"] = ChatAdministratorRights.de_json(
+            data.get("user_administrator_rights"), bot
+        )
+        data["bot_administrator_rights"] = ChatAdministratorRights.de_json(
+            data.get("bot_administrator_rights"), bot
+        )
+
+        return super().de_json(data=data, bot=bot)

_linkpreviewoptions.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the LinkPreviewOptions class."""
+
+
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.defaultvalue import DEFAULT_NONE
+from telegram._utils.types import JSONDict, ODVInput
+
+
+class LinkPreviewOptions(TelegramObject):
+    """
+    Describes the options used for link preview generation.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`is_disabled`, :attr:`url`, :attr:`prefer_small_media`,
+    :attr:`prefer_large_media`, and :attr:`show_above_text` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        is_disabled (:obj:`bool`, optional): :obj:`True`, if the link preview is disabled.
+        url (:obj:`str`, optional): The URL to use for the link preview. If empty, then the first
+            URL found in the message text will be used.
+        prefer_small_media (:obj:`bool`, optional): :obj:`True`, if the media in the link preview
+            is supposed to be shrunk; ignored if the URL isn't explicitly specified or media size
+            change isn't supported for the preview.
+        prefer_large_media (:obj:`bool`, optional): :obj:`True`, if the media in the link preview
+            is supposed to be enlarged; ignored if the URL isn't explicitly specified or media
+            size change isn't supported for the preview.
+        show_above_text (:obj:`bool`, optional): :obj:`True`, if the link preview must be shown
+            above the message text; otherwise, the link preview will be shown below the message
+            text.
+
+    Attributes:
+        is_disabled (:obj:`bool`): Optional. :obj:`True`, if the link preview is disabled.
+        url (:obj:`str`): Optional. The URL to use for the link preview. If empty, then the first
+            URL found in the message text will be used.
+        prefer_small_media (:obj:`bool`): Optional. :obj:`True`, if the media in the link preview
+            is supposed to be shrunk; ignored if the URL isn't explicitly specified or media size
+            change isn't supported for the preview.
+        prefer_large_media (:obj:`bool`): Optional. :obj:`True`, if the media in the link preview
+            is supposed to be enlarged; ignored if the URL isn't explicitly specified or media size
+            change isn't supported for the preview.
+        show_above_text (:obj:`bool`): Optional. :obj:`True`, if the link preview must be shown
+            above the message text; otherwise, the link preview will be shown below the message
+            text.
+    """
+
+    __slots__ = (
+        "is_disabled",
+        "prefer_large_media",
+        "prefer_small_media",
+        "show_above_text",
+        "url",
+    )
+
+    def __init__(
+        self,
+        is_disabled: ODVInput[bool] = DEFAULT_NONE,
+        url: ODVInput[str] = DEFAULT_NONE,
+        prefer_small_media: ODVInput[bool] = DEFAULT_NONE,
+        prefer_large_media: ODVInput[bool] = DEFAULT_NONE,
+        show_above_text: ODVInput[bool] = DEFAULT_NONE,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+
+        # Optionals
+
+        self.is_disabled: ODVInput[bool] = is_disabled
+        self.url: ODVInput[str] = url
+        self.prefer_small_media: ODVInput[bool] = prefer_small_media
+        self.prefer_large_media: ODVInput[bool] = prefer_large_media
+        self.show_above_text: ODVInput[bool] = show_above_text
+
+        self._id_attrs = (
+            self.is_disabled,
+            self.url,
+            self.prefer_small_media,
+            self.prefer_large_media,
+            self.show_above_text,
+        )
+        self._freeze()

_loginurl.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram LoginUrl."""
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class LoginUrl(TelegramObject):
+    """This object represents a parameter of the inline keyboard button used to automatically
+    authorize a user. Serves as a great replacement for the Telegram Login Widget when the user is
+    coming from Telegram. All the user needs to do is tap/click a button and confirm that they want
+    to log in. Telegram apps support these buttons as of version 5.7.
+
+    Sample bot: `@discussbot <https://t.me/discussbot>`_
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`url` is equal.
+
+    Note:
+        You must always check the hash of the received data to verify the authentication
+        and the integrity of the data as described in
+        `Checking authorization <https://core.telegram.org/widgets/login#checking-authorization>`_
+
+    Args:
+        url (:obj:`str`): An HTTPS URL to be opened with user authorization data added to the query
+            string when the button is pressed. If the user refuses to provide authorization data,
+            the original URL without information about the user will be opened. The data added is
+            the same as described in
+            `Receiving authorization data
+            <https://core.telegram.org/widgets/login#receiving-authorization-data>`_.
+        forward_text (:obj:`str`, optional): New text of the button in forwarded messages.
+        bot_username (:obj:`str`, optional): Username of a bot, which will be used for user
+            authorization. See
+            `Setting up a bot <https://core.telegram.org/widgets/login#setting-up-a-bot>`_
+            for more details. If not specified, the current
+            bot's username will be assumed. The url's domain must be the same as the domain linked
+            with the bot. See
+            `Linking your domain to the bot
+            <https://core.telegram.org/widgets/login#linking-your-domain-to-the-bot>`_
+            for more details.
+        request_write_access (:obj:`bool`, optional): Pass :obj:`True` to request the permission
+            for your bot to send messages to the user.
+
+    Attributes:
+        url (:obj:`str`): An HTTPS URL to be opened with user authorization data added to the query
+            string when the button is pressed. If the user refuses to provide authorization data,
+            the original URL without information about the user will be opened. The data added is
+            the same as described in
+            `Receiving authorization data
+            <https://core.telegram.org/widgets/login#receiving-authorization-data>`_.
+        forward_text (:obj:`str`): Optional. New text of the button in forwarded messages.
+        bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user
+            authorization. See
+            `Setting up a bot <https://core.telegram.org/widgets/login#setting-up-a-bot>`_
+            for more details. If not specified, the current
+            bot's username will be assumed. The url's domain must be the same as the domain linked
+            with the bot. See
+            `Linking your domain to the bot
+            <https://core.telegram.org/widgets/login#linking-your-domain-to-the-bot>`_
+            for more details.
+        request_write_access (:obj:`bool`): Optional. Pass :obj:`True` to request the permission
+            for your bot to send messages to the user.
+
+    """
+
+    __slots__ = ("bot_username", "forward_text", "request_write_access", "url")
+
+    def __init__(
+        self,
+        url: str,
+        forward_text: Optional[str] = None,
+        bot_username: Optional[str] = None,
+        request_write_access: Optional[bool] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.url: str = url
+        # Optional
+        self.forward_text: Optional[str] = forward_text
+        self.bot_username: Optional[str] = bot_username
+        self.request_write_access: Optional[bool] = request_write_access
+
+        self._id_attrs = (self.url,)
+
+        self._freeze()

_menubutton.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains objects related to Telegram menu buttons."""
+from typing import TYPE_CHECKING, Dict, Final, Optional, Type
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._utils import enum
+from telegram._utils.types import JSONDict
+from telegram._webappinfo import WebAppInfo
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class MenuButton(TelegramObject):
+    """This object describes the bot's menu button in a private chat. It should be one of
+
+    * :class:`telegram.MenuButtonCommands`
+    * :class:`telegram.MenuButtonWebApp`
+    * :class:`telegram.MenuButtonDefault`
+
+    If a menu button other than :class:`telegram.MenuButtonDefault` is set for a private chat,
+    then it is applied in the chat. Otherwise the default menu button is applied. By default, the
+    menu button opens the list of bot commands.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` is equal. For subclasses with additional attributes,
+    the notion of equality is overridden.
+
+    .. versionadded:: 20.0
+
+    Args:
+        type (:obj:`str`): Type of menu button that the instance represents.
+
+    Attributes:
+        type (:obj:`str`): Type of menu button that the instance represents.
+    """
+
+    __slots__ = ("type",)
+
+    def __init__(
+        self,
+        type: str,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):  # pylint: disable=redefined-builtin
+        super().__init__(api_kwargs=api_kwargs)
+        self.type: str = enum.get_member(constants.MenuButtonType, type, type)
+
+        self._id_attrs = (self.type,)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["MenuButton"]:
+        """Converts JSON data to the appropriate :class:`MenuButton` object, i.e. takes
+        care of selecting the correct subclass.
+
+        Args:
+            data (Dict[:obj:`str`, ...]): The JSON data.
+            bot (:class:`telegram.Bot`, optional): The bot associated with this object. Defaults to
+                :obj:`None`, in which case shortcut methods will not be available.
+
+                .. versionchanged:: 21.4
+                   :paramref:`bot` is now optional and defaults to :obj:`None`
+
+        Returns:
+            The Telegram object.
+
+        """
+        data = cls._parse_data(data)
+
+        if data is None:
+            return None
+
+        if not data and cls is MenuButton:
+            return None
+
+        _class_mapping: Dict[str, Type[MenuButton]] = {
+            cls.COMMANDS: MenuButtonCommands,
+            cls.WEB_APP: MenuButtonWebApp,
+            cls.DEFAULT: MenuButtonDefault,
+        }
+
+        if cls is MenuButton and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data, bot=bot)
+        return super().de_json(data=data, bot=bot)
+
+    COMMANDS: Final[str] = constants.MenuButtonType.COMMANDS
+    """:const:`telegram.constants.MenuButtonType.COMMANDS`"""
+    WEB_APP: Final[str] = constants.MenuButtonType.WEB_APP
+    """:const:`telegram.constants.MenuButtonType.WEB_APP`"""
+    DEFAULT: Final[str] = constants.MenuButtonType.DEFAULT
+    """:const:`telegram.constants.MenuButtonType.DEFAULT`"""
+
+
+class MenuButtonCommands(MenuButton):
+    """Represents a menu button, which opens the bot's list of commands.
+
+    .. include:: inclusions/menu_button_command_video.rst
+
+    .. versionadded:: 20.0
+    Attributes:
+        type (:obj:`str`): :tg-const:`telegram.constants.MenuButtonType.COMMANDS`.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=constants.MenuButtonType.COMMANDS, api_kwargs=api_kwargs)
+        self._freeze()
+
+
+class MenuButtonWebApp(MenuButton):
+    """Represents a menu button, which launches a
+    `Web App <https://core.telegram.org/bots/webapps>`_.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type`, :attr:`text` and :attr:`web_app`
+    are equal.
+
+    .. versionadded:: 20.0
+
+    Args:
+        text (:obj:`str`): Text of the button.
+        web_app (:class:`telegram.WebAppInfo`): 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 using the method :meth:`~telegram.Bot.answerWebAppQuery`
+            of :class:`~telegram.Bot`. Alternatively, a ``t.me`` link to a Web App of the bot can
+            be specified in the object instead of the Web App's URL, in which case the Web App
+            will be opened as if the user pressed the link.
+
+
+    Attributes:
+        type (:obj:`str`): :tg-const:`telegram.constants.MenuButtonType.WEB_APP`.
+        text (:obj:`str`): Text of the button.
+        web_app (:class:`telegram.WebAppInfo`): 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 using the method :meth:`~telegram.Bot.answerWebAppQuery`
+            of :class:`~telegram.Bot`. Alternatively, a ``t.me`` link to a Web App of the bot can
+            be specified in the object instead of the Web App's URL, in which case the Web App
+            will be opened as if the user pressed the link.
+    """
+
+    __slots__ = ("text", "web_app")
+
+    def __init__(self, text: str, web_app: WebAppInfo, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=constants.MenuButtonType.WEB_APP, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.text: str = text
+            self.web_app: WebAppInfo = web_app
+
+            self._id_attrs = (self.type, self.text, self.web_app)
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["MenuButtonWebApp"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["web_app"] = WebAppInfo.de_json(data.get("web_app"), bot)
+
+        return super().de_json(data=data, bot=bot)  # type: ignore[return-value]
+
+
+class MenuButtonDefault(MenuButton):
+    """Describes that no specific value for the menu button was set.
+
+    .. versionadded:: 20.0
+    Attributes:
+        type (:obj:`str`): :tg-const:`telegram.constants.MenuButtonType.DEFAULT`.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(type=constants.MenuButtonType.DEFAULT, api_kwargs=api_kwargs)
+        self._freeze()

_messageautodeletetimerchanged.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a change in the Telegram message auto
+deletion.
+"""
+
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class MessageAutoDeleteTimerChanged(TelegramObject):
+    """This object represents a service message about a change in auto-delete timer settings.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`message_auto_delete_time` is equal.
+
+    .. versionadded:: 13.4
+
+    Args:
+        message_auto_delete_time (:obj:`int`): New auto-delete time for messages in the
+            chat.
+
+    Attributes:
+        message_auto_delete_time (:obj:`int`): New auto-delete time for messages in the
+            chat.
+
+    """
+
+    __slots__ = ("message_auto_delete_time",)
+
+    def __init__(
+        self,
+        message_auto_delete_time: int,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.message_auto_delete_time: int = message_auto_delete_time
+
+        self._id_attrs = (self.message_auto_delete_time,)
+
+        self._freeze()

_messageentity.py

@@ -0,0 +1,411 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram MessageEntity."""
+
+import copy
+import itertools
+from typing import TYPE_CHECKING, Dict, Final, List, Optional, Sequence, Tuple, Union
+
+from telegram import constants
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils import enum
+from telegram._utils.strings import TextEncoding
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+_SEM = Sequence["MessageEntity"]
+
+
+class MessageEntity(TelegramObject):
+    """
+    This object represents one special entity in a text message. For example, hashtags,
+    usernames, URLs, etc.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type`, :attr:`offset` and :attr:`length` are equal.
+
+    Args:
+        type (:obj:`str`): Type of the entity. Can be :attr:`MENTION` (@username),
+            :attr:`HASHTAG` (#hashtag), :attr:`CASHTAG` ($USD), :attr:`BOT_COMMAND`
+            (/start@jobs_bot), :attr:`URL` (https://telegram.org),
+            :attr:`EMAIL` ([email protected]), :attr:`PHONE_NUMBER` (+1-212-555-0123),
+            :attr:`BOLD` (**bold text**), :attr:`ITALIC` (*italic text*), :attr:`UNDERLINE`
+            (underlined text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
+            :attr:`BLOCKQUOTE` (block quotation), :attr:`CODE` (monowidth string), :attr:`PRE`
+            (monowidth block), :attr:`TEXT_LINK` (for clickable text URLs), :attr:`TEXT_MENTION`
+            (for users without usernames), :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers).
+
+            .. versionadded:: 20.0
+                Added inline custom emoji
+
+            .. versionadded:: 20.8
+                Added block quotation
+        offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity.
+        length (:obj:`int`): Length of the entity in UTF-16 code units.
+        url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after
+            user taps on the text.
+        user (:class:`telegram.User`, optional): For :attr:`TEXT_MENTION` only, the mentioned
+             user.
+        language (:obj:`str`, optional): For :attr:`PRE` only, the programming language of
+            the entity text.
+        custom_emoji_id (:obj:`str`, optional): For :attr:`CUSTOM_EMOJI` only, unique identifier
+            of the custom emoji. Use :meth:`telegram.Bot.get_custom_emoji_stickers` to get full
+            information about the sticker.
+
+            .. versionadded:: 20.0
+    Attributes:
+        type (:obj:`str`): Type of the entity. Can be :attr:`MENTION` (@username),
+            :attr:`HASHTAG` (#hashtag), :attr:`CASHTAG` ($USD), :attr:`BOT_COMMAND`
+            (/start@jobs_bot), :attr:`URL` (https://telegram.org),
+            :attr:`EMAIL` ([email protected]), :attr:`PHONE_NUMBER` (+1-212-555-0123),
+            :attr:`BOLD` (**bold text**), :attr:`ITALIC` (*italic text*), :attr:`UNDERLINE`
+            (underlined text), :attr:`STRIKETHROUGH`, :attr:`SPOILER` (spoiler message),
+            :attr:`BLOCKQUOTE` (block quotation), :attr:`CODE` (monowidth string), :attr:`PRE`
+            (monowidth block), :attr:`TEXT_LINK` (for clickable text URLs), :attr:`TEXT_MENTION`
+            (for users without usernames), :attr:`CUSTOM_EMOJI` (for inline custom emoji stickers).
+
+            .. versionadded:: 20.0
+                Added inline custom emoji
+
+            .. versionadded:: 20.8
+                Added block quotation
+        offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity.
+        length (:obj:`int`): Length of the entity in UTF-16 code units.
+        url (:obj:`str`): Optional. For :attr:`TEXT_LINK` only, url that will be opened after
+            user taps on the text.
+        user (:class:`telegram.User`): Optional. For :attr:`TEXT_MENTION` only, the mentioned
+             user.
+        language (:obj:`str`): Optional. For :attr:`PRE` only, the programming language of
+            the entity text.
+        custom_emoji_id (:obj:`str`): Optional. For :attr:`CUSTOM_EMOJI` only, unique identifier
+            of the custom emoji. Use :meth:`telegram.Bot.get_custom_emoji_stickers` to get full
+            information about the sticker.
+
+            .. versionadded:: 20.0
+
+    """
+
+    __slots__ = ("custom_emoji_id", "language", "length", "offset", "type", "url", "user")
+
+    def __init__(
+        self,
+        type: str,  # pylint: disable=redefined-builtin
+        offset: int,
+        length: int,
+        url: Optional[str] = None,
+        user: Optional[User] = None,
+        language: Optional[str] = None,
+        custom_emoji_id: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.type: str = enum.get_member(constants.MessageEntityType, type, type)
+        self.offset: int = offset
+        self.length: int = length
+        # Optionals
+        self.url: Optional[str] = url
+        self.user: Optional[User] = user
+        self.language: Optional[str] = language
+        self.custom_emoji_id: Optional[str] = custom_emoji_id
+
+        self._id_attrs = (self.type, self.offset, self.length)
+
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["MessageEntity"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        data["user"] = User.de_json(data.get("user"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+    @staticmethod
+    def adjust_message_entities_to_utf_16(text: str, entities: _SEM) -> _SEM:
+        """Utility functionality for converting the offset and length of entities from
+        Unicode (:obj:`str`) to UTF-16 (``utf-16-le`` encoded :obj:`bytes`).
+
+        Tip:
+            Only the offsets and lengths calulated in UTF-16 is acceptable by the Telegram Bot API.
+            If they are calculated using the Unicode string (:obj:`str` object), errors may occur
+            when the text contains characters that are not in the Basic Multilingual Plane (BMP).
+            For more information, see `Unicode <https://en.wikipedia.org/wiki/Unicode>`_ and
+            `Plane (Unicode) <https://en.wikipedia.org/wiki/Plane_(Unicode)>`_.
+
+        .. versionadded:: 21.4
+
+        Examples:
+            Below is a snippet of code that demonstrates how to use this function to convert
+            entities from Unicode to UTF-16 space. The ``unicode_entities`` are calculated in
+            Unicode and the `utf_16_entities` are calculated in UTF-16.
+
+            .. code-block:: python
+
+                text = "𠌕 bold 𝄢 italic underlined: 𝛙𝌢𑁍"
+                unicode_entities = [
+                    MessageEntity(offset=2, length=4, type=MessageEntity.BOLD),
+                    MessageEntity(offset=9, length=6, type=MessageEntity.ITALIC),
+                    MessageEntity(offset=28, length=3, type=MessageEntity.UNDERLINE),
+                ]
+                utf_16_entities = MessageEntity.adjust_message_entities_to_utf_16(
+                    text, unicode_entities
+                )
+                await bot.send_message(
+                    chat_id=123,
+                    text=text,
+                    entities=utf_16_entities,
+                )
+                # utf_16_entities[0]: offset=3, length=4
+                # utf_16_entities[1]: offset=11, length=6
+                # utf_16_entities[2]: offset=30, length=6
+
+        Args:
+            text (:obj:`str`): The text that the entities belong to
+            entities (Sequence[:class:`telegram.MessageEntity`]): Sequence of entities
+                with offset and length calculated in Unicode
+
+        Returns:
+            Sequence[:class:`telegram.MessageEntity`]: Sequence of entities
+            with offset and length calculated in UTF-16 encoding
+        """
+        # get sorted positions
+        positions = sorted(itertools.chain(*((x.offset, x.offset + x.length) for x in entities)))
+        accumulated_length = 0
+        # calculate the length of each slice text[:position] in utf-16 accordingly,
+        # store the position translations
+        position_translation: Dict[int, int] = {}
+        for i, position in enumerate(positions):
+            last_position = positions[i - 1] if i > 0 else 0
+            text_slice = text[last_position:position]
+            accumulated_length += len(text_slice.encode(TextEncoding.UTF_16_LE)) // 2
+            position_translation[position] = accumulated_length
+        # get the final output entities
+        out = []
+        for entity in entities:
+            translated_positions = position_translation[entity.offset]
+            translated_length = (
+                position_translation[entity.offset + entity.length] - translated_positions
+            )
+            new_entity = copy.copy(entity)
+            with new_entity._unfrozen():
+                new_entity.offset = translated_positions
+                new_entity.length = translated_length
+            out.append(new_entity)
+        return out
+
+    @staticmethod
+    def shift_entities(by: Union[str, int], entities: _SEM) -> _SEM:
+        """Utility functionality for shifting the offset of entities by a given amount.
+
+        Examples:
+            Shifting by an integer amount:
+
+            .. code-block:: python
+
+                text = "Hello, world!"
+                entities = [
+                    MessageEntity(offset=0, length=5, type=MessageEntity.BOLD),
+                    MessageEntity(offset=7, length=5, type=MessageEntity.ITALIC),
+                ]
+                shifted_entities = MessageEntity.shift_entities(1, entities)
+                await bot.send_message(
+                    chat_id=123,
+                    text="!" + text,
+                    entities=shifted_entities,
+                )
+
+            Shifting using a string:
+
+            .. code-block:: python
+
+                text = "Hello, world!"
+                prefix = "𝄢"
+                entities = [
+                    MessageEntity(offset=0, length=5, type=MessageEntity.BOLD),
+                    MessageEntity(offset=7, length=5, type=MessageEntity.ITALIC),
+                ]
+                shifted_entities = MessageEntity.shift_entities(prefix, entities)
+                await bot.send_message(
+                    chat_id=123,
+                    text=prefix + text,
+                    entities=shifted_entities,
+                )
+
+        Tip:
+            The :paramref:`entities` are *not* modified in place. The function returns a sequence
+            of new objects.
+
+        .. versionadded:: 21.5
+
+        Args:
+            by (:obj:`str` | :obj:`int`): Either the amount to shift the offset by or
+                a string whose length will be used as the amount to shift the offset by. In this
+                case, UTF-16 encoding will be used to calculate the length.
+            entities (Sequence[:class:`telegram.MessageEntity`]): Sequence of entities
+
+        Returns:
+            Sequence[:class:`telegram.MessageEntity`]: Sequence of entities with the offset shifted
+        """
+        effective_shift = by if isinstance(by, int) else len(by.encode("utf-16-le")) // 2
+
+        out = []
+        for entity in entities:
+            new_entity = copy.copy(entity)
+            with new_entity._unfrozen():
+                new_entity.offset += effective_shift
+            out.append(new_entity)
+        return out
+
+    @classmethod
+    def concatenate(
+        cls,
+        *args: Union[Tuple[str, _SEM], Tuple[str, _SEM, bool]],
+    ) -> Tuple[str, _SEM]:
+        """Utility functionality for concatenating two text along with their formatting entities.
+
+        Tip:
+            This function is useful for prefixing an already formatted text with a new text and its
+            formatting entities. In particular, it automatically correctly handles UTF-16 encoding.
+
+        Examples:
+            This example shows a callback function that can be used to add a prefix and suffix to
+            the message in a :class:`~telegram.ext.CallbackQueryHandler`:
+
+            .. code-block:: python
+
+                async def prefix_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
+                    prefix = "𠌕 bold 𝄢 italic underlined: 𝛙𝌢𑁍 | "
+                    prefix_entities = [
+                        MessageEntity(offset=2, length=4, type=MessageEntity.BOLD),
+                        MessageEntity(offset=9, length=6, type=MessageEntity.ITALIC),
+                        MessageEntity(offset=28, length=3, type=MessageEntity.UNDERLINE),
+                    ]
+                    suffix = " | 𠌕 bold 𝄢 italic underlined: 𝛙𝌢𑁍"
+                    suffix_entities = [
+                        MessageEntity(offset=5, length=4, type=MessageEntity.BOLD),
+                        MessageEntity(offset=12, length=6, type=MessageEntity.ITALIC),
+                        MessageEntity(offset=31, length=3, type=MessageEntity.UNDERLINE),
+                    ]
+
+                    message = update.effective_message
+                    first = (prefix, prefix_entities, True)
+                    second = (message.text, message.entities)
+                    third = (suffix, suffix_entities, True)
+
+                    new_text, new_entities = MessageEntity.concatenate(first, second, third)
+                    await update.callback_query.edit_message_text(
+                        text=new_text,
+                        entities=new_entities,
+                    )
+
+        Hint:
+            The entities are *not* modified in place. The function returns a
+            new sequence of objects.
+
+        .. versionadded:: 21.5
+
+        Args:
+            *args (Tuple[:obj:`str`, Sequence[:class:`telegram.MessageEntity`]] | \
+                Tuple[:obj:`str`, Sequence[:class:`telegram.MessageEntity`], :obj:`bool`]):
+                Arbitrary number of tuples containing the text and its entities to concatenate.
+                If the last element of the tuple is a :obj:`bool`, it is used to determine whether
+                to adjust the entities to UTF-16 via
+                :meth:`adjust_message_entities_to_utf_16`. UTF-16 adjustment is disabled by
+                default.
+
+        Returns:
+            Tuple[:obj:`str`, Sequence[:class:`telegram.MessageEntity`]]: The concatenated text
+            and its entities
+        """
+        output_text = ""
+        output_entities: List[MessageEntity] = []
+        for arg in args:
+            text, entities = arg[0], arg[1]
+
+            if len(arg) > 2 and arg[2] is True:
+                entities = cls.adjust_message_entities_to_utf_16(text, entities)
+
+            output_entities.extend(cls.shift_entities(output_text, entities))
+            output_text += text
+
+        return output_text, output_entities
+
+    ALL_TYPES: Final[List[str]] = list(constants.MessageEntityType)
+    """List[:obj:`str`]: A list of all available message entity types."""
+    BLOCKQUOTE: Final[str] = constants.MessageEntityType.BLOCKQUOTE
+    """:const:`telegram.constants.MessageEntityType.BLOCKQUOTE`
+
+    .. versionadded:: 20.8
+    """
+    BOLD: Final[str] = constants.MessageEntityType.BOLD
+    """:const:`telegram.constants.MessageEntityType.BOLD`"""
+    BOT_COMMAND: Final[str] = constants.MessageEntityType.BOT_COMMAND
+    """:const:`telegram.constants.MessageEntityType.BOT_COMMAND`"""
+    CASHTAG: Final[str] = constants.MessageEntityType.CASHTAG
+    """:const:`telegram.constants.MessageEntityType.CASHTAG`"""
+    CODE: Final[str] = constants.MessageEntityType.CODE
+    """:const:`telegram.constants.MessageEntityType.CODE`"""
+    CUSTOM_EMOJI: Final[str] = constants.MessageEntityType.CUSTOM_EMOJI
+    """:const:`telegram.constants.MessageEntityType.CUSTOM_EMOJI`
+
+    .. versionadded:: 20.0
+    """
+    EMAIL: Final[str] = constants.MessageEntityType.EMAIL
+    """:const:`telegram.constants.MessageEntityType.EMAIL`"""
+    EXPANDABLE_BLOCKQUOTE: Final[str] = constants.MessageEntityType.EXPANDABLE_BLOCKQUOTE
+    """:const:`telegram.constants.MessageEntityType.EXPANDABLE_BLOCKQUOTE`
+
+    .. versionadded:: 21.3
+    """
+    HASHTAG: Final[str] = constants.MessageEntityType.HASHTAG
+    """:const:`telegram.constants.MessageEntityType.HASHTAG`"""
+    ITALIC: Final[str] = constants.MessageEntityType.ITALIC
+    """:const:`telegram.constants.MessageEntityType.ITALIC`"""
+    MENTION: Final[str] = constants.MessageEntityType.MENTION
+    """:const:`telegram.constants.MessageEntityType.MENTION`"""
+    PHONE_NUMBER: Final[str] = constants.MessageEntityType.PHONE_NUMBER
+    """:const:`telegram.constants.MessageEntityType.PHONE_NUMBER`"""
+    PRE: Final[str] = constants.MessageEntityType.PRE
+    """:const:`telegram.constants.MessageEntityType.PRE`"""
+    SPOILER: Final[str] = constants.MessageEntityType.SPOILER
+    """:const:`telegram.constants.MessageEntityType.SPOILER`
+
+    .. versionadded:: 13.10
+    """
+    STRIKETHROUGH: Final[str] = constants.MessageEntityType.STRIKETHROUGH
+    """:const:`telegram.constants.MessageEntityType.STRIKETHROUGH`"""
+    TEXT_LINK: Final[str] = constants.MessageEntityType.TEXT_LINK
+    """:const:`telegram.constants.MessageEntityType.TEXT_LINK`"""
+    TEXT_MENTION: Final[str] = constants.MessageEntityType.TEXT_MENTION
+    """:const:`telegram.constants.MessageEntityType.TEXT_MENTION`"""
+    UNDERLINE: Final[str] = constants.MessageEntityType.UNDERLINE
+    """:const:`telegram.constants.MessageEntityType.UNDERLINE`"""
+    URL: Final[str] = constants.MessageEntityType.URL
+    """:const:`telegram.constants.MessageEntityType.URL`"""

_messageid.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents an instance of a Telegram MessageId."""
+
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class MessageId(TelegramObject):
+    """This object represents a unique message identifier.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`message_id` is equal.
+
+    Args:
+        message_id (:obj:`int`): Unique message identifier.
+
+    Attributes:
+        message_id (:obj:`int`): Unique message identifier.
+    """
+
+    __slots__ = ("message_id",)
+
+    def __init__(self, message_id: int, *, api_kwargs: Optional[JSONDict] = None):
+        super().__init__(api_kwargs=api_kwargs)
+        self.message_id: int = message_id
+
+        self._id_attrs = (self.message_id,)
+
+        self._freeze()

_messageorigin.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the classes that represent Telegram MessageOigin."""
+import datetime
+from typing import TYPE_CHECKING, Dict, Final, Optional, Type
+
+from telegram import constants
+from telegram._chat import Chat
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils import enum
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class MessageOrigin(TelegramObject):
+    """
+    Base class for telegram MessageOrigin object, it can be one of:
+
+    * :class:`MessageOriginUser`
+    * :class:`MessageOriginHiddenUser`
+    * :class:`MessageOriginChat`
+    * :class:`MessageOriginChannel`
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`type` and :attr:`date` are equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        type (:obj:`str`): Type of the message origin, can be on of:
+            :attr:`~telegram.MessageOrigin.USER`, :attr:`~telegram.MessageOrigin.HIDDEN_USER`,
+            :attr:`~telegram.MessageOrigin.CHAT`, or :attr:`~telegram.MessageOrigin.CHANNEL`.
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+
+    Attributes:
+        type (:obj:`str`): Type of the message origin, can be on of:
+            :attr:`~telegram.MessageOrigin.USER`, :attr:`~telegram.MessageOrigin.HIDDEN_USER`,
+            :attr:`~telegram.MessageOrigin.CHAT`, or :attr:`~telegram.MessageOrigin.CHANNEL`.
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+    """
+
+    __slots__ = (
+        "date",
+        "type",
+    )
+
+    USER: Final[str] = constants.MessageOriginType.USER
+    """:const:`telegram.constants.MessageOriginType.USER`"""
+    HIDDEN_USER: Final[str] = constants.MessageOriginType.HIDDEN_USER
+    """:const:`telegram.constants.MessageOriginType.HIDDEN_USER`"""
+    CHAT: Final[str] = constants.MessageOriginType.CHAT
+    """:const:`telegram.constants.MessageOriginType.CHAT`"""
+    CHANNEL: Final[str] = constants.MessageOriginType.CHANNEL
+    """:const:`telegram.constants.MessageOriginType.CHANNEL`"""
+
+    def __init__(
+        self,
+        type: str,  # pylint: disable=W0622
+        date: datetime.datetime,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required by all subclasses
+        self.type: str = enum.get_member(constants.MessageOriginType, type, type)
+        self.date: datetime.datetime = date
+
+        self._id_attrs = (
+            self.type,
+            self.date,
+        )
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["MessageOrigin"]:
+        """Converts JSON data to the appropriate :class:`MessageOrigin` object, i.e. takes
+        care of selecting the correct subclass.
+        """
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        _class_mapping: Dict[str, Type[MessageOrigin]] = {
+            cls.USER: MessageOriginUser,
+            cls.HIDDEN_USER: MessageOriginHiddenUser,
+            cls.CHAT: MessageOriginChat,
+            cls.CHANNEL: MessageOriginChannel,
+        }
+        if cls is MessageOrigin and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
+
+        if "sender_user" in data:
+            data["sender_user"] = User.de_json(data.get("sender_user"), bot)
+
+        if "sender_chat" in data:
+            data["sender_chat"] = Chat.de_json(data.get("sender_chat"), bot)
+
+        if "chat" in data:
+            data["chat"] = Chat.de_json(data.get("chat"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class MessageOriginUser(MessageOrigin):
+    """
+    The message was originally sent by a known user.
+
+    .. versionadded:: 20.8
+
+    Args:
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        sender_user (:class:`telegram.User`): User that sent the message originally.
+
+    Attributes:
+        type (:obj:`str`): Type of the message origin. Always
+            :tg-const:`~telegram.MessageOrigin.USER`.
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        sender_user (:class:`telegram.User`): User that sent the message originally.
+    """
+
+    __slots__ = ("sender_user",)
+
+    def __init__(
+        self,
+        date: datetime.datetime,
+        sender_user: User,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.USER, date=date, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.sender_user: User = sender_user
+
+
+class MessageOriginHiddenUser(MessageOrigin):
+    """
+    The message was originally sent by an unknown user.
+
+    .. versionadded:: 20.8
+
+    Args:
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        sender_user_name (:obj:`str`): Name of the user that sent the message originally.
+
+    Attributes:
+        type (:obj:`str`): Type of the message origin. Always
+            :tg-const:`~telegram.MessageOrigin.HIDDEN_USER`.
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        sender_user_name (:obj:`str`): Name of the user that sent the message originally.
+    """
+
+    __slots__ = ("sender_user_name",)
+
+    def __init__(
+        self,
+        date: datetime.datetime,
+        sender_user_name: str,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.HIDDEN_USER, date=date, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.sender_user_name: str = sender_user_name
+
+
+class MessageOriginChat(MessageOrigin):
+    """
+    The message was originally sent on behalf of a chat to a group chat.
+
+    .. versionadded:: 20.8
+
+    Args:
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        sender_chat (:class:`telegram.Chat`): Chat that sent the message originally.
+        author_signature (:obj:`str`, optional): For messages originally sent by an anonymous chat
+            administrator, original message author signature
+
+    Attributes:
+        type (:obj:`str`): Type of the message origin. Always
+            :tg-const:`~telegram.MessageOrigin.CHAT`.
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        sender_chat (:class:`telegram.Chat`): Chat that sent the message originally.
+        author_signature (:obj:`str`): Optional. For messages originally sent by an anonymous chat
+            administrator, original message author signature
+    """
+
+    __slots__ = (
+        "author_signature",
+        "sender_chat",
+    )
+
+    def __init__(
+        self,
+        date: datetime.datetime,
+        sender_chat: Chat,
+        author_signature: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.CHAT, date=date, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.sender_chat: Chat = sender_chat
+            self.author_signature: Optional[str] = author_signature
+
+
+class MessageOriginChannel(MessageOrigin):
+    """
+    The message was originally sent to a channel chat.
+
+    .. versionadded:: 20.8
+
+    Args:
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        chat (:class:`telegram.Chat`): Channel chat to which the message was originally sent.
+        message_id (:obj:`int`): Unique message identifier inside the chat.
+        author_signature (:obj:`str`, optional): Signature of the original post author.
+
+    Attributes:
+        type (:obj:`str`): Type of the message origin. Always
+            :tg-const:`~telegram.MessageOrigin.CHANNEL`.
+        date (:obj:`datetime.datetime`): Date the message was sent originally.
+            |datetime_localization|
+        chat (:class:`telegram.Chat`): Channel chat to which the message was originally sent.
+        message_id (:obj:`int`): Unique message identifier inside the chat.
+        author_signature (:obj:`str`): Optional. Signature of the original post author.
+    """
+
+    __slots__ = (
+        "author_signature",
+        "chat",
+        "message_id",
+    )
+
+    def __init__(
+        self,
+        date: datetime.datetime,
+        chat: Chat,
+        message_id: int,
+        author_signature: Optional[str] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(type=self.CHANNEL, date=date, api_kwargs=api_kwargs)
+
+        with self._unfrozen():
+            self.chat: Chat = chat
+            self.message_id: int = message_id
+            self.author_signature: Optional[str] = author_signature

_messagereactionupdated.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <[email protected]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains an object that represents a Telegram MessageReaction Update."""
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional, Sequence, Tuple
+
+from telegram._chat import Chat
+from telegram._reaction import ReactionCount, ReactionType
+from telegram._telegramobject import TelegramObject
+from telegram._user import User
+from telegram._utils.argumentparsing import parse_sequence_arg
+from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
+from telegram._utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class MessageReactionCountUpdated(TelegramObject):
+    """This class represents reaction changes on a message with anonymous reactions.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if the :attr:`chat`, :attr:`message_id`, :attr:`date` and :attr:`reactions`
+    is equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        chat (:class:`telegram.Chat`): The chat containing the message.
+        message_id (:obj:`int`): Unique message identifier inside the chat.
+        date (:class:`datetime.datetime`): Date of the change in Unix time
+            |datetime_localization|
+        reactions (Sequence[:class:`telegram.ReactionCount`]): List of reactions that are present
+            on the message
+
+    Attributes:
+        chat (:class:`telegram.Chat`): The chat containing the message.
+        message_id (:obj:`int`): Unique message identifier inside the chat.
+        date (:class:`datetime.datetime`): Date of the change in Unix time
+            |datetime_localization|
+        reactions (Tuple[:class:`telegram.ReactionCount`]): List of reactions that are present on
+            the message
+    """
+
+    __slots__ = (
+        "chat",
+        "date",
+        "message_id",
+        "reactions",
+    )
+
+    def __init__(
+        self,
+        chat: Chat,
+        message_id: int,
+        date: datetime,
+        reactions: Sequence[ReactionCount],
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.chat: Chat = chat
+        self.message_id: int = message_id
+        self.date: datetime = date
+        self.reactions: Tuple[ReactionCount, ...] = parse_sequence_arg(reactions)
+
+        self._id_attrs = (self.chat, self.message_id, self.date, self.reactions)
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["MessageReactionCountUpdated"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["reactions"] = ReactionCount.de_list(data.get("reactions"), bot)
+
+        return super().de_json(data=data, bot=bot)
+
+
+class MessageReactionUpdated(TelegramObject):
+    """This class represents a change of a reaction on a message performed by a user.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if the :attr:`chat`, :attr:`message_id`, :attr:`date`, :attr:`old_reaction`
+    and :attr:`new_reaction` is equal.
+
+    .. versionadded:: 20.8
+
+    Args:
+        chat (:class:`telegram.Chat`): The chat containing the message.
+        message_id (:obj:`int`): Unique message identifier inside the chat.
+        date (:class:`datetime.datetime`): Date of the change in Unix time.
+            |datetime_localization|
+        old_reaction (Sequence[:class:`telegram.ReactionType`]): Previous list of reaction types
+            that were set by the user.
+        new_reaction (Sequence[:class:`telegram.ReactionType`]): New list of reaction types that
+            were set by the user.
+        user (:class:`telegram.User`, optional): The user that changed the reaction, if the user
+            isn't anonymous.
+        actor_chat (:class:`telegram.Chat`, optional): The chat on behalf of which the reaction was
+            changed, if the user is anonymous.
+
+    Attributes:
+        chat (:class:`telegram.Chat`): The chat containing the message.
+        message_id (:obj:`int`): Unique message identifier inside the chat.
+        date (:class:`datetime.datetime`): Date of the change in Unix time.
+            |datetime_localization|
+        old_reaction (Tuple[:class:`telegram.ReactionType`]): Previous list of reaction types
+            that were set by the user.
+        new_reaction (Tuple[:class:`telegram.ReactionType`]): New list of reaction types that
+            were set by the user.
+        user (:class:`telegram.User`): Optional. The user that changed the reaction, if the user
+            isn't anonymous.
+        actor_chat (:class:`telegram.Chat`): Optional. The chat on behalf of which the reaction was
+            changed, if the user is anonymous.
+    """
+
+    __slots__ = (
+        "actor_chat",
+        "chat",
+        "date",
+        "message_id",
+        "new_reaction",
+        "old_reaction",
+        "user",
+    )
+
+    def __init__(
+        self,
+        chat: Chat,
+        message_id: int,
+        date: datetime,
+        old_reaction: Sequence[ReactionType],
+        new_reaction: Sequence[ReactionType],
+        user: Optional[User] = None,
+        actor_chat: Optional[Chat] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        # Required
+        self.chat: Chat = chat
+        self.message_id: int = message_id
+        self.date: datetime = date
+        self.old_reaction: Tuple[ReactionType, ...] = parse_sequence_arg(old_reaction)
+        self.new_reaction: Tuple[ReactionType, ...] = parse_sequence_arg(new_reaction)
+
+        # Optional
+        self.user: Optional[User] = user
+        self.actor_chat: Optional[Chat] = actor_chat
+
+        self._id_attrs = (
+            self.chat,
+            self.message_id,
+            self.date,
+            self.old_reaction,
+            self.new_reaction,
+        )
+        self._freeze()
+
+    @classmethod
+    def de_json(
+        cls, data: Optional[JSONDict], bot: Optional["Bot"] = None
+    ) -> Optional["MessageReactionUpdated"]:
+        """See :meth:`telegram.TelegramObject.de_json`."""
+        data = cls._parse_data(data)
+
+        if not data:
+            return None
+
+        # Get the local timezone from the bot if it has defaults
+        loc_tzinfo = extract_tzinfo_from_defaults(bot)
+
+        data["date"] = from_timestamp(data.get("date"), tzinfo=loc_tzinfo)
+        data["chat"] = Chat.de_json(data.get("chat"), bot)
+        data["old_reaction"] = ReactionType.de_list(data.get("old_reaction"), bot)
+        data["new_reaction"] = ReactionType.de_list(data.get("new_reaction"), bot)
+        data["user"] = User.de_json(data.get("user"), bot)
+        data["actor_chat"] = Chat.de_json(data.get("actor_chat"), bot)
+
+        return super().de_json(data=data, bot=bot)