Bump version to v13.13

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

.deepsource.toml

@@ -0,0 +1,20 @@
+version = 1
+
+test_patterns = ["tests/**"]
+
+exclude_patterns = [
+    "tests/**",
+    "docs/**",
+    "telegram/vendor/**",
+    "setup.py",
+    "setup-raw.py"
+]
+
+[[analyzers]]
+name = "python"
+enabled = true
+
+  [analyzers.meta]
+  runtime_version = "3.x.x"
+  max_line_length = 99
+  skip_doc_coverage = ["module", "magic", "init", "nonpublic"]

.git-blame-ignore-revs

@@ -1,7 +0,0 @@
-# .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

.github/CONTRIBUTING.rst

@@ -1,11 +1,10 @@
-=================
 How To Contribute
 =================
 
 Every open source project lives from the generous help by contributors that sacrifice their time and ``python-telegram-bot`` is no different. To make participation as pleasant as possible, this project adheres to the `Code of Conduct`_ by the Python Software Foundation.
 
 Setting things up
-=================
+-----------------
 
 1. Fork the ``python-telegram-bot`` repository to your GitHub account.
 
@@ -13,7 +12,7 @@ Setting things up
 
    .. code-block:: bash
 
-      $ git clone https://github.com/<your username>/python-telegram-bot
+      $ git clone https://github.com/<your username>/python-telegram-bot --recursive
       $ cd python-telegram-bot
 
 3. Add a track to the original repository:
@@ -26,7 +25,7 @@ Setting things up
 
    .. code-block:: bash
 
-      $ pip install -r requirements-dev-all.txt
+      $ pip install -r requirements.txt -r requirements-dev.txt
 
 
 5. Install pre-commit hooks:
@@ -36,18 +35,18 @@ Setting things up
       $ pre-commit install
 
 Finding something to do
-=======================
+#######################
 
 If you already know what you'd like to work on, you can skip this section.
 
 If you have an idea for something to do, first check if it's already been filed on the `issue tracker`_. If so, add a comment to the issue saying you'd like to work on it, and we'll help you get started! Otherwise, please file a new issue and assign yourself to it.
 
-Another great way to start contributing is by writing tests. Tests are really important because they help prevent developers from accidentally breaking existing code, allowing them to build cool things faster. If you're interested in helping out, let the development team know by posting to the `Telegram group`_, and we'll help you get started.
+Another great way to start contributing is by writing tests. Tests are really important because they help prevent developers from accidentally breaking existing code, allowing them to build cool things faster. If you're interested in helping out, let the development team know by posting to the `Telegram group`_ (use `@admins` to mention the maintainers), and we'll help you get started.
 
 That being said, we want to mention that we are very hesitant about adding new requirements to our projects. If you intend to do this, please state this in an issue and get a verification from one of the maintainers.
 
 Instructions for making a code change
-=====================================
+#####################################
 
 The central development branch is ``master``, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of ``master``.
 
@@ -67,34 +66,66 @@ Here's how to make a one-off code change.
       $ git checkout -b your-branch-name
 
 3. **Make a commit to your feature branch**. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
-   We also have a check-list for PRs `below`_.
 
    - You can refer to relevant issues in the commit message by writing, e.g., "#105".
 
    - Your code should adhere to the `PEP 8 Style Guide`_, with the exception that we have a maximum line length of 99.
 
-   - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram._utils.types``.
+   - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram.utils.helpers.typing``.
 
-   - Document your code. This step is pretty important to us, so it has its own `section`_.
+   - Document your code. This project uses `sphinx`_ to generate static HTML docs. To build them, first make sure you have the required dependencies:
+
+     .. code-block:: bash
+
+        $ pip install -r docs/requirements-docs.txt
+
+     then run the following from the PTB root directory:
+   
+     .. code-block:: bash
+         
+        $ make -C docs html
+
+     or, if you don't have ``make`` available (e.g. on Windows):
+
+     .. code-block:: bash
+
+        $ sphinx-build docs/source docs/build/html
+
+     Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser.
+
+   - Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed.
 
    - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_.
 
    - The following exceptions to the above (Google's) style guides applies:
 
-     - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
+        - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
 
-   -  In addition, PTB uses some formatting/styling and linting tools in the pre-commit setup. Some of those tools also have command line tools that can help to run these tools outside of the pre-commit step. If you'd like to leverage that, please have a look at the `pre-commit config file`_ for an overview of which tools (and which versions of them) are used. For example, we use `Black`_ for code formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.
+   -  In addition, PTB uses the `Black`_ coder formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.
 
-   - Please ensure that the code you write is well-tested and that all automated tests still pass. We
-     have dedicated an `testing page`_ to help you with that.
+   - Please ensure that the code you write is well-tested.
 
-   - Don't break backward compatibility.
+   - Don’t break backward compatibility.
 
    - Add yourself to the AUTHORS.rst_ file in an alphabetical fashion.
 
+   - Before making a commit ensure that all automated tests still pass:
+
+     .. code-block::
+
+        $ pytest -v
+
+     To run ``test_official`` (particularly useful if you made API changes), run
+
+     .. code-block::
+
+        $ export TEST_OFFICIAL=true
+
+     prior to running the tests.
+
    - If you want run style & type checks before committing run
 
-     .. code-block:: bash
+     .. code-block::
 
         $ pre-commit run -a
 
@@ -120,13 +151,11 @@ Here's how to make a one-off code change.
 
 5. **Address review comments until all reviewers give LGTM ('looks good to me').**
 
-   - When your reviewer has reviewed the code, you'll get a notification. You'll need to respond in two ways:
+   - When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways:
 
-     - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
+       - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
 
-     - In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.
-
-     - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
+       - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
 
    - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:
 
@@ -140,6 +169,12 @@ Here's how to make a one-off code change.
         $ git commit -a
         $ git push origin your-branch-name
 
+   - If after merging you see local modified files in ``telegram/vendor/`` directory, that you didn't actually touch, that means you need to update submodules with this command:
+
+     .. code-block:: bash
+
+        $ git submodule update --init --recursive
+
    - At the end, the reviewer will merge the pull request.
 
 6. **Tidy up!** Delete the feature branch from both your local clone and the GitHub repository:
@@ -151,97 +186,11 @@ Here's how to make a one-off code change.
 
 7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
 
-Check-list for PRs
+Style commandments
 ------------------
 
-This checklist is a non-exhaustive reminder of things that should be done before a PR is merged, both for you as contributor and for the maintainers.
-Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
-
-.. code-block:: markdown
-
-    ## Check-list for PRs
-
-    - [ ] Added `.. versionadded:: NEXT.VERSION`, ``.. versionchanged:: NEXT.VERSION``, ``.. deprecated:: NEXT.VERSION`` or ``.. versionremoved:: NEXT.VERSION` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
-    - [ ] Created new or adapted existing unit tests
-    - [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html)
-    - [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
-    - [ ] Added new classes & modules to the docs and all suitable ``__all__`` s
-    - [ ] Checked the [Stability Policy](https://docs.python-telegram-bot.org/stability_policy.html) in case of deprecations or changes to documented behavior
-
-    **If the PR contains API changes (otherwise, you can ignore this passage)**
-
-    - [ ] Checked the Bot API specific sections of the [Stability Policy](https://docs.python-telegram-bot.org/stability_policy.html)
-    - [ ] Created a PR to remove functionality deprecated in the previous Bot API release ([see here](https://docs.python-telegram-bot.org/en/stable/stability_policy.html#case-2))
-
-    - New Classes
-
-        - [ ] Added `self._id_attrs` and corresponding documentation
-        - [ ] `__init__` accepts `api_kwargs` as keyword-only
-
-    - Added New Shortcuts
-
-        - [ ] In [`telegram.Chat`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.chat.html) \& [`telegram.User`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.user.html) for all methods that accept `chat/user_id`
-        - [ ] In [`telegram.Message`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.message.html) for all methods that accept `chat_id` and `message_id`
-        - [ ] For new `telegram.Message` shortcuts: Added `quote` argument if methods accept `reply_to_message_id`
-        - [ ] In [`telegram.CallbackQuery`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.callbackquery.html) for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
-
-    - If Relevant
-
-        - [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
-        - [ ] Linked new and existing constants in docstrings instead of hard-coded numbers and strings
-        - [ ] Added new message types to `telegram.Message.effective_attachment`
-        - [ ] Added new handlers for new update types
-            - [ ] Added the handlers to the warning loop in the [`telegram.ext.ConversationHandler`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.conversationhandler.html)
-        - [ ] Added new filters for new message (sub)types
-        - [ ] Added or updated documentation for the changed class(es) and/or method(s)
-        - [ ] Added the new method(s) to `_extbot.py`
-        - [ ] Added or updated `bot_methods.rst`
-        - [ ] Updated the Bot API version number in all places: `README.rst` (including the badge) and `telegram.constants.BOT_API_VERSION_INFO`
-        - [ ] Added logic for arbitrary callback data in `telegram.ext.ExtBot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains [`telegram.Message`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.message.html)
-
-Documenting
-===========
-
-The documentation of this project is separated in two sections: User facing and dev facing.
-
-User facing docs are hosted at `RTD`_. They are the main way the users of our library are supposed to get information about the objects. They don't care about the internals, they just want to know
-what they have to pass to make it work, what it actually does. You can/should provide examples for non obvious cases (like the Filter module), and notes/warnings.
-
-Dev facing, on the other side, is for the devs/maintainers of this project. These
-doc strings don't have a separate documentation site they generate, instead, they document the actual code.
-
-User facing documentation
--------------------------
-We use `sphinx`_ to generate static HTML docs. To build them, first make sure you're running Python 3.10 or above and have the required dependencies installed as explained above.
-Then, run the following from the PTB root directory:
-
-.. code-block:: bash
-
-   $ make -C docs html
-
-or, if you don't have ``make`` available (e.g. on Windows):
-
-.. code-block:: bash
-
-   $ sphinx-build docs/source docs/build/html
-
-Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser.
-
-- Add ``.. versionadded:: NEXT.VERSION``, ``.. versionchanged:: NEXT.VERSION`` or ``.. deprecated:: NEXT.VERSION`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed.
-
-Dev facing documentation
-------------------------
-We adhere to the `CSI`_ standard. This documentation is not fully implemented in the project, yet, but new code changes should comply with the `CSI` standard.
-The idea behind this is to make it very easy for you/a random maintainer or even a totally foreign person to drop anywhere into the code and more or less immediately understand what a particular line does. This will make it easier
-for new to make relevant changes if said lines don't do what they are supposed to.
-
-
-
-Style commandments
-==================
-
 Assert comparison order
------------------------
+#######################
 
 Assert statements should compare in **actual** == **expected** order.
 For example (assuming ``test_call`` is the thing being tested):
@@ -255,7 +204,7 @@ For example (assuming ``test_call`` is the thing being tested):
     assert 5 == test_call()
 
 Properly calling callables
---------------------------
+##########################
 
 Methods, functions and classes can specify optional parameters (with default
 values) using Python's keyword arg syntax. When providing a value to such a
@@ -272,23 +221,35 @@ callable we prefer that the call also uses keyword arg syntax. For example:
 This gives us the flexibility to re-order arguments and more importantly
 to add new required arguments. It's also more explicit and easier to read.
 
+Properly defining optional arguments
+####################################
 
-.. _`Code of Conduct`: https://policies.python.org/python.org/code-of-conduct/
+It's always good to not initialize optional arguments at class creation,
+instead use ``**kwargs`` to get them. It's well known Telegram API can
+change without notice, in that case if a new argument is added it won't
+break the API classes. For example:
+
+.. code-block:: python
+
+    # GOOD
+    def __init__(self, id, name, last_name=None, **kwargs):
+       self.last_name = last_name
+
+    # BAD
+    def __init__(self, id, name, last_name=None):
+       self.last_name = last_name
+
+
+.. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/
 .. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues
 .. _`Telegram group`: https://telegram.me/pythontelegrambotgroup
-.. _`PEP 8 Style Guide`: https://peps.python.org/pep-0008/
-.. _`sphinx`: https://www.sphinx-doc.org/en/master
-.. _`Google Python Style Guide`: https://google.github.io/styleguide/pyguide.html
+.. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/
+.. _`sphinx`: http://sphinx-doc.org
+.. _`Google Python Style Guide`: http://google.github.io/styleguide/pyguide.html
 .. _`Google Python Style Docstrings`: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
-.. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst
+.. _AUTHORS.rst: ../AUTHORS.rst
 .. _`MyPy`: https://mypy.readthedocs.io/en/stable/index.html
 .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
-.. _`pre-commit config file`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.pre-commit-config.yaml
 .. _`Black`: https://black.readthedocs.io/en/stable/index.html
-.. _`popular editors`: https://black.readthedocs.io/en/stable/integrations/editors.html
-.. _`RTD`: https://docs.python-telegram-bot.org/
-.. _`RTD build`: https://docs.python-telegram-bot.org/en/doc-fixes
-.. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html
-.. _`section`: #documenting
-.. _`testing page`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/tests/README.rst
-.. _`below`: #check-list-for-prs
+.. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html
+.. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,7 +1,7 @@
 name: Bug Report
 description: Create a report to help us improve
-labels: ["📋 triage"]
-type: '🐛 bug'
+title: "[BUG]"
+labels: ["bug :bug:"]
 
 body:
   - type: markdown

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -1,7 +1,7 @@
 name: Feature Request
 description: Suggest an idea for this project
-labels: ["📋 triage"]
-type: '💡 feature'
+title: "[FEATURE]"
+labels: ["enhancement"]
 
 body:
   - type: textarea

.github/ISSUE_TEMPLATE/question.yml

@@ -1,7 +1,7 @@
 name: Question
 description: Get help with errors or general questions
+title: "[QUESTION]"
 labels: ["question"]
-type: '❔ question'
 
 body:
   - type: markdown
@@ -12,8 +12,6 @@ body:
         To make it easier for us to help you, please read this [article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Ask-Right).
 
         Please mind that there is also a users' [Telegram group](https://t.me/pythontelegrambotgroup) for questions about the library. Questions asked there might be answered quicker than here. Moreover, [GitHub Discussions](https://github.com/python-telegram-bot/python-telegram-bot/discussions) offer a slightly better format to discuss usage questions.
-        
-        If you have asked the same question elsewhere (e.g. the [Telegram group](https://t.me/pythontelegrambotgroup) or [StackOverflow](https://stackoverflow.com/questions/tagged/python-telegram-bot)), provide a link to that thread.
 
   - type: textarea
     id: issue-faced

.github/dependabot.yml

@@ -1,20 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "friday"
-    labels:
-      - "⚙️ dependencies"
-      - "🔗 python"
-
-  # Updates the dependencies of the GitHub Actions workflows
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "monthly"
-      day: "friday"
-    labels:
-      - "⚙️ dependencies"
-      - "🔗 github-actions"

.github/labeler.yml

@@ -1,9 +0,0 @@
-# Config file for workflows/labelling.yml
-
-version: 1
-
-labels:
-- label: "⚙️ dependencies"
-  authors: ["dependabot[bot]", "pre-commit-ci[bot]"]
-- label: "🛠 code-quality"
-  authors: ["pre-commit-ci[bot]"]

.github/pull_request_template.md

@@ -1,6 +1,32 @@
 <!--
-Hey! You're PRing? Cool!
-Please be sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
-Especially, please have a look at the check list for PRs (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst#check-list-for-prs). Feel free to copy (parts of) the checklist to the PR description to remind you or the maintainers of open points or if you have questions on anything.
+Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to help both you and the maintainers to remember some aspects. Make sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
 -->
 
+### Checklist for PRs
+
+- [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
+- [ ] Created new or adapted existing unit tests
+- [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
+- [ ] Added new classes & modules to the docs
+
+
+### If the PR contains API changes (otherwise, you can delete this passage)
+
+* New classes:
+    - [ ] Added `self._id_attrs` and corresponding documentation
+    - [ ] `__init__` accepts `**_kwargs`
+    
+* Added new shortcuts:
+    - [ ] In `Chat` & `User` for all methods that accept `chat/user_id`
+    - [ ] In `Message` for all methods that accept `chat_id` and `message_id`
+    - [ ] For new `Message` shortcuts: Added `quote` argument if methods accepts `reply_to_message_id`
+    - [ ] In `CallbackQuery` for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
+    
+* If relevant:
+
+    - [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
+    - [ ] Added new handlers for new update types
+    - [ ] Added new filters for new message (sub)types
+    - [ ] Added or updated documentation for the changed class(es) and/or method(s)
+    - [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION`
+    - [ ] Added logic for arbitrary callback data in `tg.ext.Bot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains `telegram.Message`

.github/stale.yml

@@ -0,0 +1,14 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 3
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 2
+# Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled)
+onlyLabels: question
+# Label to use when marking an issue as stale
+staleLabel: stale
+# Comment to post when marking as stale. Set to `false` to disable
+markComment: false
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: >
+  This issue has been automatically closed due to inactivity. Feel free to comment in order to reopen
+  or ask again in our Telegram support group at https://t.me/pythontelegrambotgroup.

.github/workflows/assets/release_template.html

@@ -1,5 +0,0 @@
-<b>We've just released {tag}</b>.
-Thank you to everyone who contributed to this release.
-As usual, upgrade using <code>pip install -U python-telegram-bot</code>.
-
-The release notes can be found <a href="https://docs.python-telegram-bot.org/en/{tag}/changelog.html">here</a>.

.github/workflows/chango.yml

@@ -1,66 +0,0 @@
-name: Chango
-on:
-  pull_request:
-    types:
-      - opened
-      - reopened
-      - synchronize
-
-permissions: {}
-
-jobs:
-  create-chango-fragment:
-    permissions:
-      # Give the default GITHUB_TOKEN write permission to commit and push the
-      # added or changed files to the repository.
-      contents: write
-    name: Create chango Fragment
-    runs-on: ubuntu-latest
-    outputs:
-      IS_RELEASE_PR: ${{ steps.check_title.outputs.IS_RELEASE_PR }}
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          # needed for commit and push step at the end
-          persist-credentials: true
-      - name: Check PR Title
-        id: check_title
-        run: | # zizmor: ignore[template-injection]
-          if [[ "$(echo "${{ github.event.pull_request.title }}" | tr '[:upper:]' '[:lower:]')" =~ ^bump\ version\ to\ .* ]]; then
-            echo "COMMIT_AND_PUSH=false" >> $GITHUB_OUTPUT
-            echo "IS_RELEASE_PR=true" >> $GITHUB_OUTPUT
-          else
-            echo "COMMIT_AND_PUSH=true" >> $GITHUB_OUTPUT
-            echo "IS_RELEASE_PR=false" >> $GITHUB_OUTPUT
-          fi
-
-      # Create the new fragment
-      - uses: Bibo-Joshi/chango@9d6bd9d7612eca5fab2c5161687011be59baaf19 # v0.4.0
-        with:
-          github-token: ${{ secrets.CHANGO_PAT }}
-          query-issue-types: true
-          commit-and-push: ${{ steps.check_title.outputs.COMMIT_AND_PUSH }}
-
-      # Run `chango release` if applicable - needs some additional setup.
-      - name: Set up Python
-        if: steps.check_title.outputs.IS_RELEASE_PR == 'true'
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
-        with:
-          python-version: "3.x"
-
-      - name: Do Release
-        if: steps.check_title.outputs.IS_RELEASE_PR == 'true'
-        run: |
-          cd ./target-repo
-          git add changes/unreleased/*
-          pip install . -r docs/requirements-docs.txt
-          VERSION_TAG=$(python -c "from telegram import __version__; print(f'{__version__}')")
-          chango release --uid $VERSION_TAG
-
-      - name: Commit & Push
-        if: steps.check_title.outputs.IS_RELEASE_PR == 'true'
-        uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5.2.0
-        with:
-          commit_message: "Do chango Release"
-          repository: ./target-repo

.github/workflows/dependabot-prs.yml

@@ -1,41 +0,0 @@
-name: Process Dependabot PRs
-
-on:
-  pull_request:
-    types: [opened, reopened]
-
-permissions: {}
-
-jobs:
-  process-dependabot-prs:
-    permissions:
-      pull-requests: read
-      contents: write
-
-    runs-on: ubuntu-latest
-    if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}
-    steps:
-
-    - name: Fetch Dependabot metadata
-      id: dependabot-metadata
-      uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 # v2.3.0
-
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-      with:
-        ref: ${{ github.event.pull_request.head.ref }}
-        persist-credentials: false
-
-    - name: Update Version Number in Other Files
-      uses: jacobtomlinson/gha-find-replace@f1069b438f125e5395d84d1c6fd3b559a7880cb5 # v3
-      with:
-        find: ${{ steps.dependabot-metadata.outputs.previous-version }}
-        replace: ${{ steps.dependabot-metadata.outputs.new-version }}
-        regex: false
-        exclude: CHANGES.rst
-
-    - name: Commit & Push Changes to PR
-      uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5 # v9.1.4
-      with:
-        message: 'Update version number in other files'
-        committer_name: GitHub Actions
-        committer_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/docs-admonitions.yml

@@ -1,41 +0,0 @@
-name: Test Admonitions Generation
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - docs/**
-      - .github/workflows/docs-admonitions.yml
-  push:
-    branches:
-      - master
-
-permissions: {}
-
-jobs:
-  test-admonitions:
-    name: Test Admonitions Generation
-    runs-on: ${{matrix.os}}
-    permissions:
-      # for uploading artifacts
-      actions: write
-    strategy:
-      matrix:
-        python-version: ['3.12']
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: 'pip'
-          cache-dependency-path: '**/requirements*.txt'
-      - name: Install dependencies
-        run: |
-          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install -r requirements-dev-all.txt
-      - name: Test autogeneration of admonitions
-        run: pytest -v --tb=short tests/docs/admonition_inserter.py

.github/workflows/docs-linkcheck.yml

@@ -1,41 +0,0 @@
-name: Check Links in Documentation
-on:
-  schedule:
-    # First day of month at 05:46 in every 2nd month
-    - cron: '46 5 1 */2 *'
-  pull_request:
-    paths:
-      - .github/workflows/docs-linkcheck.yml
-
-permissions: {}
-
-jobs:
-  test-sphinx-build:
-    name: test-sphinx-linkcheck
-    runs-on: ${{matrix.os}}
-    strategy:
-      matrix:
-        python-version: ['3.12']
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: |
-          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install -r requirements-dev-all.txt
-      - name: Check Links
-        run: sphinx-build docs/source docs/build/html --keep-going -j auto -b linkcheck
-      - name: Upload linkcheck output
-        # Run also if the previous steps failed
-        if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: linkcheck-output
-          path: docs/build/html/output.*

.github/workflows/example_notifier.yml

@@ -0,0 +1,14 @@
+name: Warning maintainers
+on:
+  pull_request:
+    paths: examples/**
+jobs:
+  job:
+    runs-on: ubuntu-latest
+    name: about example change
+    steps:
+      - name: running the check
+        uses: Poolitzer/notifier-action@master
+        with:
+          notify-message: Hey there. Relax, I am just a little warning for the maintainers to release directly after merging your PR, otherwise we have broken examples and people might get confused :)
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/gha_security.yml

@@ -1,33 +0,0 @@
-name: GitHub Actions Security Analysis
-
-on:
-  push:
-    branches:
-      - master
-  pull_request:
-
-permissions: {}
-
-jobs:
-  zizmor:
-    name: Security Analysis with zizmor
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      security-events: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
-      - name: Run zizmor
-        run: uvx zizmor --persona=pedantic --format sarif . > results.sarif
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Upload SARIF file
-        uses: github/codeql-action/upload-sarif@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16
-        with:
-          sarif_file: results.sarif
-          category: zizmor

.github/workflows/labelling.yml

@@ -1,19 +0,0 @@
-name: PR Labeler
-
-on:
-  pull_request:
-    types: [opened]
-
-permissions: {}
-
-jobs:
-  pre-commit-ci:
-    permissions:
-      contents: read # for srvaroa/labeler to read config file
-      pull-requests: write # for srvaroa/labeler to add labels in PR
-    runs-on: ubuntu-latest
-    steps:
-    - uses: srvaroa/labeler@0a20eccb8c94a1ee0bed5f16859aece1c45c3e55 # v1.13.0
-      # Config file at .github/labeler.yml
-      env:
-        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/lock.yml

@@ -3,23 +3,16 @@ name: 'Lock Closed Threads'
 on:
   schedule:
     - cron: '8 4 * * *'
-
-permissions: {}
+    - cron: '42 17 * * *'
 
 jobs:
   lock:
     runs-on: ubuntu-latest
-    permissions:
-      # For locking the threads
-      issues: write
-      pull-requests: write
     steps:
-      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5.0.1
+      - uses: dessant/lock-threads@v2.0.1
         with:
           github-token: ${{ github.token }}
-          issue-inactive-days: '7'
+          issue-lock-inactive-days: '7'
           issue-lock-reason: ''
-          pr-inactive-days: '7'
+          pr-lock-inactive-days: '7'
           pr-lock-reason: ''
-          # Don't lock Discussions
-          process-only: 'issues, prs'

.github/workflows/pre-commit_dependencies_notifier.yml

@@ -0,0 +1,17 @@
+name: Warning maintainers
+on:
+  pull_request:
+    paths:
+      - requirements.txt
+      - requirements-dev.txt
+      - .pre-commit-config.yaml
+jobs:
+  job:
+    runs-on: ubuntu-latest
+    name: about pre-commit and dependency change
+    steps:
+      - name: running the check
+        uses: Poolitzer/notifier-action@master
+        with:
+          notify-message: Hey! Looks like you edited the (dev) requirements or the pre-commit hooks. I'm just a friendly reminder to keep the pre-commit hook versions in sync with the dev requirements and the additional dependencies for the hooks in sync with the requirements :)
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/readme_notifier.yml

@@ -0,0 +1,16 @@
+name: Warning maintainers
+on:
+  pull_request:
+    paths:
+      - README.rst
+      - README_RAW.rst
+jobs:
+  job:
+    runs-on: ubuntu-latest
+    name: about readme change
+    steps:
+      - name: running the check
+        uses: Poolitzer/notifier-action@master
+        with:
+          notify-message: Hey! Looks like you edited README.rst or README_RAW.rst. I'm just a friendly reminder to apply relevant changes to both of those files :)
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release_pypi.yml

@@ -1,170 +0,0 @@
-name: Publish to PyPI
-
-on:
-  # manually trigger the workflow
-  workflow_dispatch:
-
-permissions: {}
-
-jobs:
-  build:
-    name: Build Distribution
-    runs-on: ubuntu-latest
-    outputs:
-      TAG: ${{ steps.get_tag.outputs.TAG }}
-    permissions:
-      # for uploading artifacts
-      actions: write
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Set up Python
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
-        with:
-          python-version: "3.x"
-      - name: Install pypa/build
-        run: >-
-          python3 -m pip install build --user
-      - name: Build a binary wheel and a source tarball
-        run: python3 -m build
-      - name: Store the distribution packages
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: python-package-distributions
-          path: dist/
-      - name: Get Tag Name
-        id: get_tag
-        run: |
-          pip install .
-          TAG=$(python -c "from telegram import __version__; print(f'v{__version__}')")
-          echo "TAG=$TAG" >> $GITHUB_OUTPUT
-
-  publish-to-pypi:
-    name: Publish to PyPI
-    needs:
-      - build
-    runs-on: ubuntu-latest
-    environment:
-      name: release_pypi
-      url: https://pypi.org/p/python-telegram-bot
-    permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
-      actions: read  # for downloading artifacts
-
-    steps:
-      - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: python-package-distributions
-          path: dist/
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
-
-  compute-signatures:
-    name: Compute SHA1 Sums and Sign with Sigstore
-    runs-on: ubuntu-latest
-    needs:
-      - publish-to-pypi
-
-    permissions:
-      id-token: write  # IMPORTANT: mandatory for sigstore
-      actions: write  # for up/downloading artifacts
-
-    steps:
-      - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: python-package-distributions
-          path: dist/
-      - name: Compute SHA1 Sums
-        run: |
-          # Compute SHA1 sum of the distribution packages and save it to a file with the same name,
-          # but with .sha1 extension
-          for file in dist/*; do
-              sha1sum $file > $file.sha1
-          done
-      - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
-        with:
-          inputs: >-
-            ./dist/*.tar.gz
-            ./dist/*.whl
-      - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: python-package-distributions-and-signatures
-          path: dist/
-
-  github-release:
-    name: Upload to GitHub Release
-    needs:
-      - build
-      - compute-signatures
-
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: write  # IMPORTANT: mandatory for making GitHub Releases
-      actions: read  # for downloading artifacts
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: python-package-distributions-and-signatures
-          path: dist/
-      - name: Create GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          TAG: ${{ needs.build.outputs.TAG }}
-        # Create a tag and a GitHub Release. The description is filled by the static template, we
-        # just insert the correct tag in the template.
-        run: >-
-          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
-          gh release create
-          "$TAG"
-          --repo '${{ github.repository }}'
-          --notes-file -
-      - name: Upload artifact signatures to GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          TAG: ${{ needs.build.outputs.TAG }}
-        # Upload to GitHub Release using the `gh` CLI.
-        # `dist/` contains the built packages, and the
-        # sigstore-produced signatures and certificates.
-        run: >-
-          gh release upload
-          "$TAG" dist/**
-          --repo '${{ github.repository }}'
-
-  telegram-channel:
-    name: Publish to Telegram Channel
-    needs:
-        - github-release
-
-    runs-on: ubuntu-latest
-    environment:
-      name: release_pypi
-    permissions: {}
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Publish to Telegram Channel
-        env:
-          TAG: ${{ needs.build.outputs.TAG }}
-          # This secret is configured only for the `pypi-release` branch
-          BOT_TOKEN: ${{ secrets.CHANNEL_BOT_TOKEN }}
-        run: >-
-          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
-          curl
-          -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage"
-          -d "chat_id=@pythontelegrambotchannel"
-          -d "parse_mode=HTML"
-          --data-urlencode "text@-"

.github/workflows/release_test_pypi.yml

@@ -1,146 +0,0 @@
-name: Publish to Test PyPI
-
-on:
-  # manually trigger the workflow
-  workflow_dispatch:
-
-permissions: {}
-
-jobs:
-  build:
-    name: Build Distribution
-    runs-on: ubuntu-latest
-    outputs:
-      TAG: ${{ steps.get_tag.outputs.TAG }}
-    permissions:
-      # for uploading artifacts
-      actions: write
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Set up Python
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
-        with:
-          python-version: "3.x"
-      - name: Install pypa/build
-        run: >-
-          python3 -m pip install build --user
-      - name: Build a binary wheel and a source tarball
-        run: python3 -m build
-      - name: Store the distribution packages
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: python-package-distributions
-          path: dist/
-      - name: Get Tag Name
-        id: get_tag
-        run: |
-          pip install .
-          TAG=$(python -c "from telegram import __version__; print(f'v{__version__}')")
-          echo "TAG=$TAG" >> $GITHUB_OUTPUT
-
-  publish-to-test-pypi:
-    name: Publish to Test PyPI
-    needs:
-      - build
-    runs-on: ubuntu-latest
-    environment:
-      name: release_test_pypi
-      url: https://test.pypi.org/p/python-telegram-bot
-    permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
-      actions: read  # for downloading artifacts
-
-    steps:
-      - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: python-package-distributions
-          path: dist/
-      - name: Publish to Test PyPI
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
-        with:
-          repository-url: https://test.pypi.org/legacy/
-
-  compute-signatures:
-    name: Compute SHA1 Sums and Sign with Sigstore
-    runs-on: ubuntu-latest
-    needs:
-      - publish-to-test-pypi
-
-    permissions:
-      id-token: write  # IMPORTANT: mandatory for sigstore
-      actions: write  # for up/downloading artifacts
-
-    steps:
-      - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: python-package-distributions
-          path: dist/
-      - name: Compute SHA1 Sums
-        run: |
-          # Compute SHA1 sum of the distribution packages and save it to a file with the same name,
-          # but with .sha1 extension
-          for file in dist/*; do
-              sha1sum $file > $file.sha1
-          done
-      - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
-        with:
-          inputs: >-
-            ./dist/*.tar.gz
-            ./dist/*.whl
-      - name: Store the distribution packages and signatures
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: python-package-distributions-and-signatures
-          path: dist/
-
-  github-test-release:
-    name: Upload to GitHub Release Draft
-    needs:
-      - build
-      - compute-signatures
-
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: write  # IMPORTANT: mandatory for making GitHub Releases
-      actions: read  # for downloading artifacts
-
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Download all the dists
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
-        with:
-          name: python-package-distributions-and-signatures
-          path: dist/
-      - name: Create GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          TAG: ${{ needs.build.outputs.TAG }}
-        # Create a tag and a GitHub Release *draft*. The description is filled by the static
-        # template, we just insert the correct tag in the template.
-        run: >-
-          sed "s/{tag}/$TAG/g" .github/workflows/assets/release_template.html |
-          gh release create
-          "$TAG"
-          --repo '${{ github.repository }}'
-          --draft
-          --notes-file -
-      - name: Upload artifact signatures to GitHub Release
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          TAG: ${{ needs.build.outputs.TAG }}
-        # Upload to GitHub Release using the `gh` CLI.
-        # `dist/` contains the built packages, and the
-        # sigstore-produced signatures and certificates.
-        run: >-
-          gh release upload
-          "$TAG" dist/**
-          --repo '${{ github.repository }}'

.github/workflows/stale.yml

@@ -1,24 +0,0 @@
-name: 'Mark & close stale questions'
-on:
-  schedule:
-    - cron: '42 2 * * *'
-
-permissions: {}
-
-jobs:
-  stale:
-    runs-on: ubuntu-latest
-    permissions:
-      # For adding labels and closing
-      issues: write
-    steps:
-      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.0
-        with:
-          # PRs never get stale
-          days-before-stale: 3
-          days-before-close: 2
-          days-before-pr-stale: -1
-          stale-issue-label: '📋 stale'
-          only-labels: 'question'
-          stale-issue-message: ''
-          close-issue-message: 'This issue has been automatically closed due to inactivity. Feel free to comment in order to reopen or ask again in our Telegram support group at https://t.me/pythontelegrambotgroup.'

.github/workflows/test.yml

@@ -0,0 +1,98 @@
+name: GitHub Actions
+on:
+  pull_request:
+    branches:
+      - master
+      - v13.x
+  push:
+    branches: 
+      - master
+      - v13.x
+
+jobs:
+  pytest:
+    name: pytest
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        python-version: [3.7, 3.8, 3.9]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+      fail-fast: False
+    steps:
+      - uses: actions/checkout@v2
+      - name: Initialize vendored libs
+        run:
+          git submodule update --init --recursive
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -W ignore -m pip install --upgrade pip
+          python -W ignore -m pip install -U codecov pytest-cov
+          python -W ignore -m pip install -r requirements.txt
+          python -W ignore -m pip install -r requirements-dev.txt
+
+      - name: Test with pytest
+        # We run 3 different suites here
+        # 1. Test just utils.helpers.py without pytz being installed
+        # 2. Test just test_no_passport.py without passport dependencies being installed
+        # 3. Test everything else
+        # The first & second one are achieved by mocking the corresponding import
+        # See test_helpers.py & test_no_passport.py for details
+        run: |
+          pytest -v --cov -k test_no_passport.py
+          no_passport_exit=$?
+          export TEST_NO_PASSPORT='false'
+          pytest -v --cov --cov-append -k test_helpers.py
+          no_pytz_exit=$?
+          export TEST_NO_PYTZ='false'
+          pytest -v --cov --cov-append
+          full_exit=$?
+          special_exit=$(( no_pytz_exit > no_passport_exit ? no_pytz_exit : no_passport_exit ))
+          global_exit=$(( special_exit > full_exit ? special_exit : full_exit ))
+          exit ${global_exit}
+        env:
+          JOB_INDEX: ${{ strategy.job-index }}
+          BOTS: W3sidG9rZW4iOiAiNjk2MTg4NzMyOkFBR1Z3RUtmSEhsTmpzY3hFRE5LQXdraEdzdFpfa28xbUMwIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WldGaU1UUmxNbVF5TnpNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMi43IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzkwOTgzOTk3IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzI3X2JvdCJ9LCB7InRva2VuIjogIjY3MTQ2ODg4NjpBQUdQR2ZjaVJJQlVORmU4MjR1SVZkcTdKZTNfWW5BVE5HdyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpHWXdPVGxrTXpNeE4yWTIiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ0NjAyMjUyMiIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zNF9ib3QifSwgeyJ0b2tlbiI6ICI2MjkzMjY1Mzg6QUFGUnJaSnJCN29CM211ekdzR0pYVXZHRTVDUXpNNUNVNG8iLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNbU01WVdKaFl6a3hNMlUxIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgQ1B5dGhvbiAzLjUiLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDE0OTY5MTc3NTAiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX2NweXRob25fMzVfYm90In0sIHsidG9rZW4iOiAiNjQwMjA4OTQzOkFBRmhCalFwOXFtM1JUeFN6VXBZekJRakNsZS1Kano1aGNrIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WXpoa1pUZzFOamMxWXpWbCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMy42IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzMzODcxNDYxIiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzM2X2JvdCJ9LCB7InRva2VuIjogIjY5NTEwNDA4ODpBQUhmenlsSU9qU0lJUy1lT25JMjB5MkUyMEhvZEhzZnotMCIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk9HUTFNRGd3WmpJd1pqRmwiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNyIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ3ODI5MzcxNCIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zN19ib3QifSwgeyJ0b2tlbiI6ICI2OTE0MjM1NTQ6QUFGOFdrakNaYm5IcVBfaTZHaFRZaXJGRWxackdhWU9oWDAiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpZamM1TlRoaU1tUXlNV1ZoIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgUHlQeSAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEzNjM5MzI1NzMiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX3B5cHlfMjdfYm90In0sIHsidG9rZW4iOiAiNjg0MzM5OTg0OkFBRk1nRUVqcDAxcjVyQjAwN3lDZFZOc2c4QWxOc2FVLWNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TVRBek1UWTNNR1V5TmpnMCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIFB5UHkgMy41IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDA3ODM2NjA1IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19weXB5XzM1X2JvdCJ9LCB7InRva2VuIjogIjY5MDA5MTM0NzpBQUZMbVI1cEFCNVljcGVfbU9oN3pNNEpGQk9oMHozVDBUbyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpEaGxOekU1TURrd1lXSmkiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIEFwcFZleW9yIHVzaW5nIENQeXRob24gMy40IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMjc5NjAwMDI2IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX2FwcHZleW9yX2NweXRob25fMzRfYm90In0sIHsidG9rZW4iOiAiNjk0MzA4MDUyOkFBRUIyX3NvbkNrNTVMWTlCRzlBTy1IOGp4aVBTNTVvb0JBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WW1aaVlXWm1NakpoWkdNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gQXBwVmV5b3IgdXNpbmcgQ1B5dGhvbiAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEyOTMwNzkxNjUiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfYXBwdmV5b3JfY3B5dGhvbl8yN19ib3QifSwgeyJ0b2tlbiI6ICIxMDU1Mzk3NDcxOkFBRzE4bkJfUzJXQXd1SjNnN29oS0JWZ1hYY2VNbklPeVNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TmpBd056QXpZalZpTkdOayIsICJuYW1lIjogIlBUQiB0ZXN0cyBbMF0iLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDExODU1MDk2MzYiLCAidXNlcm5hbWUiOiAicHRiXzBfYm90In0sIHsidG9rZW4iOiAiMTA0NzMyNjc3MTpBQUY4bk90ODFGcFg4bGJidno4VWV3UVF2UmZUYkZmQnZ1SSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOllUVTFOVEk0WkdSallqbGkiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzFdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDg0Nzk3NjEyIiwgInVzZXJuYW1lIjogInB0Yl8xX2JvdCJ9LCB7InRva2VuIjogIjk3MTk5Mjc0NTpBQUdPa09hVzBOSGpnSXY1LTlqUWJPajR2R3FkaFNGLVV1cyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk5XWmtNV1ZoWWpsallqVTUiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzJdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDAyMjU1MDcwIiwgInVzZXJuYW1lIjogInB0Yl8yX2JvdCJ9XQ==
+          TEST_NO_PYTZ : "true"
+          TEST_NO_PASSPORT: "true"
+          TEST_BUILD: "true"
+        shell: bash --noprofile --norc {0}
+
+      - name: Submit coverage
+        uses: codecov/codecov-action@v1
+        with:
+          env_vars: OS,PYTHON
+          name: ${{ matrix.os }}-${{ matrix.python-version }}
+          fail_ci_if_error: true
+  test_official:
+    name: test-official
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        python-version: [3.7]
+        os: [ubuntu-latest]
+      fail-fast: False
+    steps:
+      - uses: actions/checkout@v2
+      - name: Initialize vendored libs
+        run:
+          git submodule update --init --recursive
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -W ignore -m pip install --upgrade pip
+          python -W ignore -m pip install -r requirements.txt
+          python -W ignore -m pip install -r requirements-dev.txt
+      - name: Compare to official api
+        run: |
+          pytest -v tests/test_official.py
+          exit $?
+        env:
+          TEST_OFFICIAL: "true"
+        shell: bash --noprofile --norc {0}

.github/workflows/test_official.yml

@@ -1,51 +0,0 @@
-name: Bot API Tests
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - tests/**
-  push:
-    branches:
-      - master
-  schedule:
-    # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
-    - cron: '7 3 * * 1,5'
-
-permissions: {}
-
-jobs:
-  check-conformity:
-    name: check-conformity
-    runs-on: ${{matrix.os}}
-    strategy:
-      matrix:
-        python-version: [3.11]
-        os: [ubuntu-latest]
-      fail-fast: False
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: |
-          python -W ignore -m pip install --upgrade pip
-          python -W ignore -m pip install .[all]
-          python -W ignore -m pip install -r requirements-unit-tests.txt
-      - name: Compare to official api
-        run: |
-          pytest -v tests/test_official/test_official.py --junit-xml=.test_report_official.xml
-          exit $?
-        env:
-          TEST_OFFICIAL: "true"
-        shell: bash --noprofile --norc {0}
-
-      - name: Test Summary
-        id: test_summary
-        uses: test-summary/action@31493c76ec9e7aa675f1585d3ed6f1da69269a86 # v2.4
-        if: always()  # always run, even if tests fail
-        with:
-          paths: .test_report_official.xml

.github/workflows/type_completeness.yml

@@ -1,23 +0,0 @@
-name: Check Type Completeness
-on:
-  pull_request:
-    paths:
-      - telegram/**
-      - pyproject.toml
-      - .github/workflows/type_completeness.yml
-  push:
-    branches:
-      - master
-
-permissions: {}
-
-jobs:
-  test-type-completeness:
-    name:   test-type-completeness
-    runs-on: ubuntu-latest
-    steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@c85a67ff3c66f51dcbb2d06bfcf4fe83a57d69cc # v1.0.1
-        with:
-          package-name: telegram
-          python-version: 3.12
-          pyright-version: ~=1.1.367

.github/workflows/type_completeness_monthly.yml

@@ -1,35 +0,0 @@
-name: Check Type Completeness Monthly Run
-on:
-  schedule:
-    # Run first friday of the month at 03:17 - odd time to spread load on GitHub Actions
-    - cron: '17 3 1-7 * 5'
-
-permissions: {}
-
-jobs:
-  test-type-completeness:
-    name:   test-type-completeness
-    runs-on: ubuntu-latest
-    steps:
-      - uses: Bibo-Joshi/pyright-type-completeness@c85a67ff3c66f51dcbb2d06bfcf4fe83a57d69cc # v1.0.1
-        id: pyright-type-completeness
-        with:
-          package-name: telegram
-          python-version: 3.12
-          pyright-version: ~=1.1.367
-      - name: Check Output
-        uses: jannekem/run-python-script-action@bbfca66c612a28f3eeca0ae40e1f810265e2ea68 # v1.7
-        env:
-          TYPE_COMPLETENESS: ${{ steps.pyright-type-completeness.outputs.base-completeness-score }}
-        with:
-          script: |
-            import os
-            completeness = float(os.getenv("TYPE_COMPLETENESS"))
-            
-            if completeness >= 1:
-                exit(0)
-            
-            text = f"Type Completeness Decreased to {completeness}. ❌"
-            error(text)
-            set_summary(text)
-            exit(1)

.gitignore

@@ -51,8 +51,6 @@ nosetests.xml
 coverage.xml
 *,cover
 .coveralls.yml
-.testmondata
-.testmondata-journal
 
 # Translations
 *.mo
@@ -67,14 +65,10 @@ docs/_build/
 # PyBuilder
 target/
 .idea/
-.run/
 
 # Sublime Text 2
 *.sublime*
 
-# VS Code
-.vscode
-
 # unitests files
 game.gif
 telegram.mp3
@@ -93,6 +87,3 @@ telegram.jpg
 
 # virtual env
 venv*
-
-# environment manager:
-.mise.toml

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "telegram/vendor/urllib3"]
+	path = telegram/vendor/ptb_urllib3
+	url = https://github.com/python-telegram-bot/urllib3.git
+	branch = ptb

.pre-commit-config.yaml

@@ -1,83 +1,64 @@
-# Make sure that the additional_dependencies here match pyproject.toml
+# Make sure that
+#   * the revs specified here match requirements-dev.txt
+#   * the additional_dependencies here match requirements.txt
 
 ci:
-    autofix_prs: false
-    autoupdate_schedule: quarterly
-    autoupdate_commit_msg: 'Bump `pre-commit` Hooks to Latest Versions'
+    # We currently only need this behavior on the v13.x branch were we have the vendored urllib
+    submodules: true
 
 repos:
--   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.11.9'
-    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,<1.3
--   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 25.1.0
+-   repo: https://github.com/psf/black
+    rev: 22.3.0
     hooks:
     -   id: black
         args:
         - --diff
         - --check
--   repo: https://github.com/PyCQA/flake8
-    rev: 7.2.0
+-   repo: https://gitlab.com/pycqa/flake8
+    rev: 3.9.2
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v3.3.6
+    rev: v2.8.3
     hooks:
     -   id: pylint
-        files: ^(?!(tests|docs)).*\.py$
+        files: ^(telegram|examples)/.*\.py$
+        args:
+          - --rcfile=setup.cfg
         additional_dependencies:
-          - httpx~=0.27
-          - tornado~=6.4
-          - APScheduler~=3.10.4
-          - cachetools>=5.3.3,<5.5.0
-          - aiolimiter~=1.1,<1.3
+          - certifi
+          - tornado>=6.1
+          - APScheduler==3.6.3
+          - cachetools==4.2.2
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.15.0
+    rev: v0.812
     hooks:
     -   id: mypy
         name: mypy-ptb
-        files: ^(?!(tests|examples|docs)).*\.py$
+        files: ^telegram/.*\.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,<1.3
+          - certifi
+          - tornado>=6.1
+          - APScheduler==3.6.3
+          - cachetools==4.2.2
+          - . # this basically does `pip install -e .`
+    -   id: mypy
+        name: mypy-examples
+        files: ^examples/.*\.py$
+        args:
+          - --no-strict-optional
+          - --follow-imports=silent
+        additional_dependencies:
+          - certifi
+          - tornado>=6.1
+          - APScheduler==3.6.3
+          - cachetools==4.2.2
           - . # 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.19.1
+    rev: v2.19.1
     hooks:
     -   id: pyupgrade
+        files: ^(telegram|examples|tests)/.*\.py$
         args:
-          - --py39-plus
--   repo: https://github.com/pycqa/isort
-    rev: 6.0.1
-    hooks:
-    -   id: isort
-        name: isort
-        args:
-        - --diff
-        - --check
+          - --py36-plus

.readthedocs.yml

@@ -7,56 +7,16 @@ version: 2
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: docs/source/conf.py
+   configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF
 formats:
-  - pdf
+   - pdf
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  install:
-    - method: pip
-      path: .
-    - requirements: requirements-dev-all.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'
+   version: 3
+   install:
+     - method: pip
+       path: .
+     - requirements: docs/requirements-docs.txt

AUTHORS.rst

@@ -7,44 +7,42 @@ 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>`_
-- `Abdelrahman <https://github.com/aelkheir>`_
 
 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>`_.
 
+Vendored packages
+-----------------
+
+We're vendoring urllib3 as part of ``python-telegram-bot`` which is distributed under the MIT
+license. For more info, full credits & license terms, the sources can be found here:
+`https://github.com/python-telegram-bot/urllib3`.
+
 Contributors
 ------------
 
 The following wonderful people contributed directly or indirectly to this project:
 
-- `Aditya <https://github.com/clot27>`_
 - `Abshar <https://github.com/abxhr>`_
-- `Abubakar Alaya <https://github.com/Ecode2>`_
 - `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>`_
-- `Anya Marcano <https://github.com/AnyaMarcanito>`
 - `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>`_
-- `Dmitry Kolomatskiy <https://github.com/lemontree210>`_
 - `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>`_
@@ -53,19 +51,14 @@ The following wonderful people contributed directly or indirectly to this projec
 - `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>`_
-- `Henry Galue <https://github.com/henryg311>`
 - `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>`_
-- `Jeamhowards Montiel <https://github.com/Jeam-zx>`
 - `jeffffc <https://github.com/jeffffc>`_
 - `Jelle Besseling <https://github.com/pingiun>`_
 - `jh0ker <https://github.com/jh0ker>`_
@@ -74,26 +67,15 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Joscha Götzer <https://github.com/Rostgnom>`_
 - `jossalgon <https://github.com/jossalgon>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
-- `Juan Cuevas <https://github.com/cuevasrja>`
-- `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>`_
-- `Luis Pérez <https://github.com/nemacysts>`_
 - `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>`_
-- `Miguel Salomon <https://github.com/Migueldsc12>`
-- `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>`_
@@ -104,26 +86,18 @@ The following wonderful people contributed directly or indirectly to this projec
 - `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>`_
-- Snehashish Biswas
 - `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 <https://github.com/Starry69>`_
-- `Shivam Saini <https://github.com/shivamsn97>`_
-- `Siloé Garcez <https://github.com/roast-lord>`_
 - `Simon Schürrle <https://github.com/SitiSchu>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
 - `syntx <https://github.com/syntx>`_
@@ -135,12 +109,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `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.

CODE_OF_CONDUCT.md

@@ -1,14 +1,10 @@
-====================================
-Contributor Covenant Code of Conduct
-====================================
+# Contributor Covenant Code of Conduct
 
-Our Pledge
-==========
+## 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
-=============
+## Our Standards
 
 Examples of behavior that contributes to creating a positive environment include:
 
@@ -27,26 +23,25 @@ Examples of unacceptable behavior by participants include:
 * 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
-====================
+## 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
-=====
+## 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
-===========
+## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at devs@python-telegram-bot.org. 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
-===========
+## 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/>`_.
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE LICENSE.lesser Makefile requirements.txt README_RAW.rst telegram/py.typed

README.rst

@@ -1,8 +1,17 @@
-.. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png
+..
+    Make sure to apply any changes to this file to README_RAW.rst as well!
+
+.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
    :align: center
    :target: https://python-telegram-bot.org
    :alt: python-telegram-bot Logo
 
+We have made you a wrapper you can't refuse
+
+We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+
+*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
+
 .. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg
    :target: https://pypi.org/project/python-telegram-bot/
    :alt: PyPi Package Version
@@ -11,225 +20,222 @@
    :target: https://pypi.org/project/python-telegram-bot/
    :alt: Supported Python versions
 
-.. image:: https://img.shields.io/badge/Bot%20API-9.0-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-6.1-blue?logo=telegram
    :target: https://core.telegram.org/bots/api-changelog
-   :alt: Supported Bot API version
+   :alt: Supported Bot API versions
 
 .. image:: https://img.shields.io/pypi/dm/python-telegram-bot
    :target: https://pypistats.org/packages/python-telegram-bot
    :alt: PyPi Package Monthly Download
 
-.. image:: https://app.readthedocs.org/projects/python-telegram-bot/badge/?version=stable
-   :target: https://docs.python-telegram-bot.org/en/stable/
+.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
+   :target: https://python-telegram-bot.readthedocs.io/en/stable/?badge=stable
    :alt: Documentation Status
 
 .. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
    :target: https://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
-.. image:: https://github.com/python-telegram-bot/python-telegram-bot/actions/workflows/unit_tests.yml/badge.svg?branch=master
+.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 
 .. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
-   :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
+   :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
 
-.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
-   :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
+.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
+   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
    :alt: Median time to resolve an issue
 
 .. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
-   :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
+   :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=python-telegram-bot/python-telegram-bot&amp;utm_campaign=Badge_Grade
    :alt: Code quality: Codacy
 
-.. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg
-   :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master
-   :alt: pre-commit.ci status
+.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
+   :target: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
+   :alt: Code quality: DeepSource
 
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
-   :alt: Code Style: Black
-
-.. image:: https://img.shields.io/badge/Telegram-Channel-blue.svg?logo=telegram
-   :target: https://t.me/pythontelegrambotchannel
-   :alt: Telegram Channel
 
 .. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram
    :target: https://telegram.me/pythontelegrambotgroup
    :alt: Telegram Group
 
-We have made you a wrapper you can't refuse
+=================
+Table of contents
+=================
 
-We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+- `Introduction`_
 
-*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
+- `Telegram API support`_
 
+- `Installing`_
+
+- `Getting started`_
+
+  #. `Learning by example`_
+
+  #. `Logging`_
+
+  #. `Documentation`_
+
+- `Getting help`_
+
+- `Contributing`_
+
+- `License`_
+
+
+============
 Introduction
-------------
+============
 
-This library provides a pure Python, asynchronous interface for the
+This library provides a pure Python interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions **3.9+**.
+It's compatible with Python versions 3.7+. PTB might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
 
-In addition to the pure API implementation, this library features several convenience methods and shortcuts as well as a number of high-level classes to
+In addition to the pure API implementation, this library features a number of high-level classes to
 make the development of bots easy and straightforward. These classes are contained in the
 ``telegram.ext`` submodule.
 
-After installing_ the library, be sure to check out the section on `working with PTB`_.
+A pure API implementation *without* ``telegram.ext`` is available as the standalone package ``python-telegram-bot-raw``.  `See here for details. <https://github.com/python-telegram-bot/python-telegram-bot/blob/v13.x/README_RAW.rst>`_
 
+----
+Note
+----
+
+Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both.
+
+====================
 Telegram API support
-~~~~~~~~~~~~~~~~~~~~
+====================
 
-All types and methods of the Telegram Bot API **9.0** are natively supported by this library.
-In addition, Bot API functionality not yet natively included can still be used as described `in our wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_.
-
-Notable Features
-~~~~~~~~~~~~~~~~
-
-- `Fully asynchronous <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
-- Convenient shortcut methods, e.g. `Message.reply_text <https://docs.python-telegram-bot.org/en/stable/telegram.message.html#telegram.Message.reply_text>`_
-- `Fully annotated with static type hints <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Type-Checking>`_
-- `Customizable and extendable interface <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Architecture>`_
-- Seamless integration with `webhooks <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_ and `polling <https://docs.python-telegram-bot.org/en/stable/telegram.ext.application.html#telegram.ext.Application.run_polling>`_
-- `Comprehensive documentation and examples <#working-with-ptb>`_
+All types and methods of the Telegram Bot API **6.1** are supported.
 
+==========
 Installing
-----------
+==========
 
-You can install or upgrade ``python-telegram-bot`` via
+You can install or upgrade python-telegram-bot with:
 
 .. code:: shell
 
     $ pip install python-telegram-bot --upgrade
 
-To install a pre-release, use the ``--pre`` `flag <https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-pre>`_ in addition.
-
-You can also install ``python-telegram-bot`` from source, though this is usually not necessary.
+Or you can install from source with:
 
 .. code:: shell
 
-    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive
     $ cd python-telegram-bot
-    $ pip install build
-    $ python -m build
+    $ python setup.py install
+    
+In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with:
 
-Verifying Releases
-~~~~~~~~~~~~~~~~~~
+.. code:: shell
 
-To enable you to verify that a release file that you downloaded was indeed provided by the ``python-telegram-bot`` team, we have taken the following measures.
-
-Starting with v21.4, all releases are signed via `sigstore <https://www.sigstore.dev>`_.
-The corresponding signature files are uploaded to the `GitHub releases page`_.
-To verify the signature, please install the `sigstore Python client <https://pypi.org/project/sigstore/>`_ and follow the instructions for `verifying signatures from GitHub Actions <https://github.com/sigstore/sigstore-python?tab=readme-ov-file>`_. As input for the ``--repository`` parameter, please use the value ``python-telegram-bot/python-telegram-bot``.
-
-Earlier releases are signed with a GPG key.
-The signatures are uploaded to both the `GitHub releases page`_ and the `PyPI project <https://pypi.org/project/python-telegram-bot/>`_ and end with a suffix ``.asc``.
-Please find the public keys `here <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/public_keys>`_.
-The keys are named in the format ``<first_version>-<last_version>.gpg``.
-
-In addition, the GitHub release page also contains the sha1 hashes of the release files in the files with the suffix ``.sha1``.
-
-Dependencies & Their Versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
-However, for some features using a 3rd party library is more sane than implementing the functionality again.
-As these features are *optional*, the corresponding 3rd party dependencies are not installed by default.
-Instead, they are listed as optional dependencies.
-This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.
-
-The only required dependency is `httpx ~= 0.27 <https://www.python-httpx.org>`_ for
-``telegram.request.HTTPXRequest``, the default networking backend.
-
-``python-telegram-bot`` is most useful when used along with additional libraries.
-To minimize dependency conflicts, we try to be liberal in terms of version requirements on the (optional) dependencies.
-On the other hand, we have to ensure stability of ``python-telegram-bot``, which is why we do apply version bounds.
-If you encounter dependency conflicts due to these bounds, feel free to reach out.
+    $ git submodule update --init --recursive
 
+---------------------
 Optional Dependencies
-#####################
+---------------------
 
 PTB can be installed with optional dependencies:
 
-* ``pip install "python-telegram-bot[passport]"`` installs the `cryptography>=39.0.1 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install "python-telegram-bot[socks]"`` installs `httpx[socks] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
-* ``pip install "python-telegram-bot[http2]"`` installs `httpx[http2] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to use HTTP/2.
-* ``pip install "python-telegram-bot[rate-limiter]"`` installs `aiolimiter~=1.1,<1.3 <https://aiolimiter.readthedocs.io/en/stable/>`_. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
-* ``pip install "python-telegram-bot[webhooks]"`` installs the `tornado~=6.4 <https://www.tornadoweb.org/en/stable/>`_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.run_webhook``.
-* ``pip install "python-telegram-bot[callback-data]"`` installs the `cachetools>=5.3.3,<5.6.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
-* ``pip install "python-telegram-bot[job-queue]"`` installs the `APScheduler>=3.10.4,<3.12.0 <https://apscheduler.readthedocs.io/en/3.x/>`_ library. Use this, if you want to use the ``telegram.ext.JobQueue``.
+* ``pip install python-telegram-bot[passport]`` installs the `cryptography <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
+* ``pip install python-telegram-bot[ujson]`` installs the `ujson <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
+* ``pip install python-telegram-bot[socks]`` installs the `PySocks <https://pypi.org/project/PySocks/>`_ library. Use this, if you want to work behind a Socks5 server.
 
-To install multiple optional dependencies, separate them by commas, e.g. ``pip install "python-telegram-bot[socks,webhooks]"``.
+===============
+Getting started
+===============
 
-Additionally, two shortcuts are provided:
+Our Wiki contains a lot of resources to get you started with ``python-telegram-bot``:
 
-* ``pip install "python-telegram-bot[all]"`` installs all optional dependencies.
-* ``pip install "python-telegram-bot[ext]"`` installs all optional dependencies that are related to ``telegram.ext``, i.e. ``[rate-limiter, webhooks, callback-data, job-queue]``.
+- `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_
+- Tutorial: `Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_
 
-Working with PTB
-----------------
+Other references:
 
-Once you have installed the library, you can begin working with it - so let's get started!
+- `Telegram API documentation <https://core.telegram.org/bots/api>`_
+- `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
 
-Quick Start
-~~~~~~~~~~~
+-------------------
+Learning by example
+-------------------
 
-Our Wiki contains an `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_ explaining how the pure Bot API can be accessed via ``python-telegram-bot``.
-Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---Your-first-Bot>`_ gives an introduction on how chatbots can be easily programmed with the help of the ``telegram.ext`` module.
+We believe that the best way to learn this package is by example. Here
+are some examples for you to review. Even if it is not your approach for learning, please take a
+look at ``echobot.py``, it is the de facto base for most of the bots out there. Best of all,
+the code for these examples are released to the public domain, so you can start by grabbing the
+code and building on top of it.
 
-Resources
-~~~~~~~~~
+Visit `this page <https://github.com/python-telegram-bot/python-telegram-bot/blob/v13.x/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
 
-- The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
-  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
-- The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
-- Our `examples section <https://docs.python-telegram-bot.org/examples.html>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
-  Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there.
-  The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it.
-- The `official Telegram Bot API documentation <https://core.telegram.org/bots/api>`_ is of course always worth a read.
-
-Getting help
-~~~~~~~~~~~~
-
-If the resources mentioned above don't answer your questions or simply overwhelm you, there are several ways of getting help.
-
-1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us! Asking a question here is often the quickest way to get a pointer in the right direction.
-
-2. Ask questions by opening `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
-
-3. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
-
-Concurrency
-~~~~~~~~~~~
-
-Since v20.0, ``python-telegram-bot`` is built on top of Pythons ``asyncio`` module.
-Because ``asyncio`` is in general single-threaded, ``python-telegram-bot`` does currently not aim to be thread-safe.
-Noteworthy parts of ``python-telegram-bots`` API that are likely to cause issues (e.g. race conditions) when used in a multi-threaded setting include:
-
-* ``telegram.ext.Application/Updater.update_queue``
-* ``telegram.ext.ConversationHandler.check/handle_update``
-* ``telegram.ext.CallbackDataCache``
-* ``telegram.ext.BasePersistence``
-* all classes in the ``telegram.ext.filters`` module that allow to add/remove allowed users/chats at runtime
-
-Contributing
-------------
-
-Contributions of all sizes are welcome.
-Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started.
-You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
-
-Donating
---------
-Occasionally we are asked if we accept donations to support the development.
-While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations.
-If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
-
-License
+-------
+Logging
 -------
 
-You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_.
-Derivative works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.
+This library uses the ``logging`` module. To set up logging to standard output, put:
 
-.. _`GitHub releases page`: https://github.com/python-telegram-bot/python-telegram-bot/releases
+.. code:: python
+
+    import logging
+    logging.basicConfig(level=logging.DEBUG,
+                        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+at the beginning of your script.
+
+You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want:
+
+.. code:: python
+
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+If you want DEBUG logs instead:
+
+.. code:: python
+
+    logger.setLevel(logging.DEBUG)
+
+
+=============
+Documentation
+=============
+
+``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_.
+
+============
+Getting help
+============
+
+You can get help in several ways:
+
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+
+2. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ or `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
+
+3. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
+
+4. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
+
+
+============
+Contributing
+============
+
+Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/v13.x/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+
+========
+Donating
+========
+Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
+
+=======
+License
+=======
+
+You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.

README_RAW.rst

@@ -0,0 +1,222 @@
+..
+    Make sure to apply any changes to this file to README.rst as well!
+
+.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-raw-logo-text_768.png?raw=true
+   :align: center
+   :target: https://python-telegram-bot.org
+   :alt: python-telegram-bot-raw Logo
+
+We have made you a wrapper you can't refuse
+
+We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+
+*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
+
+.. image:: https://img.shields.io/pypi/v/python-telegram-bot-raw.svg
+   :target: https://pypi.org/project/python-telegram-bot-raw/
+   :alt: PyPi Package Version
+
+.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot-raw.svg
+   :target: https://pypi.org/project/python-telegram-bot-raw/
+   :alt: Supported Python versions
+
+.. image:: https://img.shields.io/badge/Bot%20API-6.1-blue?logo=telegram
+   :target: https://core.telegram.org/bots/api-changelog
+   :alt: Supported Bot API versions
+
+.. image:: https://img.shields.io/pypi/dm/python-telegram-bot-raw
+   :target: https://pypistats.org/packages/python-telegram-bot-raw
+   :alt: PyPi Package Monthly Download
+
+.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
+   :target: https://python-telegram-bot.readthedocs.io/
+   :alt: Documentation Status
+
+.. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg
+   :target: https://www.gnu.org/licenses/lgpl-3.0.html
+   :alt: LGPLv3 License
+
+.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg
+   :target: https://github.com/python-telegram-bot/python-telegram-bot/
+   :alt: Github Actions workflow
+
+.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
+   :alt: Code coverage
+
+.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
+   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
+   :alt: Median time to resolve an issue
+
+.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
+   :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=python-telegram-bot/python-telegram-bot&amp;utm_campaign=Badge_Grade
+   :alt: Code quality: Codacy
+
+.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
+   :target: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
+   :alt: Code quality: DeepSource
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram
+   :target: https://telegram.me/pythontelegrambotgroup
+   :alt: Telegram Group
+
+=================
+Table of contents
+=================
+
+- `Introduction`_
+
+- `Telegram API support`_
+
+- `Installing`_
+
+- `Getting started`_
+
+  #. `Logging`_
+
+  #. `Documentation`_
+
+- `Getting help`_
+
+- `Contributing`_
+
+- `License`_
+
+============
+Introduction
+============
+
+This library provides a pure Python, lightweight interface for the
+`Telegram Bot API <https://core.telegram.org/bots/api>`_.
+It's compatible with Python versions 3.7+. PTB-Raw might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
+
+``python-telegram-bot-raw`` is part of the `python-telegram-bot <https://python-telegram-bot.org>`_ ecosystem and provides the pure API functionality extracted from PTB. It therefore does *not* have independent release schedules, changelogs or documentation. Please consult the PTB resources.
+
+----
+Note
+----
+
+Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both.
+
+====================
+Telegram API support
+====================
+
+All types and methods of the Telegram Bot API **6.1** are supported.
+
+==========
+Installing
+==========
+
+You can install or upgrade python-telegram-bot-raw with:
+
+.. code:: shell
+
+    $ pip install python-telegram-bot-raw --upgrade
+
+Or you can install from source with:
+
+.. code:: shell
+
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive
+    $ cd python-telegram-bot
+    $ python setup-raw.py install
+
+In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with:
+
+.. code:: shell
+
+    $ git submodule update --init --recursive
+
+----
+Note
+----
+
+Installing the `.tar.gz` archive available on PyPi directly via `pip` will *not* work as expected, as `pip` does not recognize that it should use `setup-raw.py` instead of `setup.py`.
+
+---------------------
+Optional Dependencies
+---------------------
+
+PTB can be installed with optional dependencies:
+
+* ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
+* ``pip install python-telegram-bot-raw[ujson]`` installs the `ujson <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
+
+===============
+Getting started
+===============
+
+Our Wiki contains an `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_. Other references are:
+
+- the `Telegram API documentation <https://core.telegram.org/bots/api>`_
+- the `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
+
+-------
+Logging
+-------
+
+This library uses the ``logging`` module. To set up logging to standard output, put:
+
+.. code:: python
+
+    import logging
+    logging.basicConfig(level=logging.DEBUG,
+                        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+at the beginning of your script.
+
+You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want:
+
+.. code:: python
+
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+If you want DEBUG logs instead:
+
+.. code:: python
+
+    logger.setLevel(logging.DEBUG)
+
+
+=============
+Documentation
+=============
+
+``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_, which
+includes the relevant documentation for ``python-telegram-bot-raw``.
+
+============
+Getting help
+============
+
+You can get help in several ways:
+
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+
+2. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ or `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
+
+3. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
+
+4. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
+
+============
+Contributing
+============
+
+Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/v13.x/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+
+========
+Donating
+========
+Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
+
+=======
+License
+=======
+
+You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.

changes/22.0_2025-03-15/4671.7B3boYRvHdGzsrZgkpKp7B.toml

@@ -1,19 +0,0 @@
-breaking = """This release removes all functionality that was deprecated in v20.x. This is in line with our :ref:`stability policy <stability-policy>`.
-This includes the following changes:
-
-- Removed ``filters.CHAT`` (all messages have an associated chat) and ``filters.StatusUpdate.USER_SHARED`` (use ``filters.StatusUpdate.USERS_SHARED`` instead).
-- Removed ``Defaults.disable_web_page_preview`` and ``Defaults.quote``. Use ``Defaults.link_preview_options`` and ``Defaults.do_quote`` instead.
-- Removed ``ApplicationBuilder.(get_updates_)proxy_url`` and ``HTTPXRequest.proxy_url``. Use ``ApplicationBuilder.(get_updates_)proxy`` and ``HTTPXRequest.proxy`` instead.
-- Removed the ``*_timeout`` arguments of ``Application.run_polling`` and ``Updater.start_webhook``. Instead, specify the values via ``ApplicationBuilder.get_updates_*_timeout``.
-- Removed ``constants.InlineQueryLimit.MIN_SWITCH_PM_TEXT_LENGTH``. Use ``constants.InlineQueryResultsButtonLimit.MAX_START_PARAMETER_LENGTH`` instead.
-- Removed the argument ``quote`` of ``Message.reply_*``. Use ``do_quote`` instead.
-- Removed the superfluous ``EncryptedPassportElement.credentials`` without replacement.
-- Changed attribute value of ``PassportFile.file_date`` from :obj:`int` to :class:`datetime.datetime`. Make sure to adjust your code accordingly.
-- Changed the attribute value of ``PassportElementErrors.file_hashes`` from :obj:`list` to :obj:`tuple`. Make sure to adjust your code accordingly.
-- Make ``BaseRequest.read_timeout`` an abstract property. If you subclass ``BaseRequest``, you need to implement this property.
-- The default value for ``write_timeout`` now defaults to ``DEFAULT_NONE`` also for bot methods that send media. Previously, it was ``20``. If you subclass ``BaseRequest``, make sure to use your desired write timeout if ``RequestData.multipart_data`` is set.
-"""
-[[pull_requests]]
-uid = "4671"
-author_uid = "Bibo-Joshi"
-closes_threads = ["4659"]

changes/22.0_2025-03-15/4672.G9szuJ7pRafycByfem2DrT.toml

@@ -1,5 +0,0 @@
-documentation = "Add `chango <https://chango.readthedocs.io/stable/>`_ As Changelog Management Tool"
-[[pull_requests]]
-uid = "4672"
-author_uid = "Bibo-Joshi"
-closes_threads = ["4321"]

changes/22.0_2025-03-15/4697.GzyGCEgj74G6bTEDbuFjUU.toml

@@ -1,5 +0,0 @@
-internal = "Bump github/codeql-action from 3.28.8 to 3.28.10"
-[[pull_requests]]
-uid = "4697"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4698.Fkzr3oU2qcFmFX28xfoja5.toml

@@ -1,5 +0,0 @@
-internal = "Bump srvaroa/labeler from 1.12.0 to 1.13.0"
-[[pull_requests]]
-uid = "4698"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4699.LYAYfKXX7C7wqT54kRPnVy.toml

@@ -1,5 +0,0 @@
-internal = "Bump astral-sh/setup-uv from 5.2.2 to 5.3.1"
-[[pull_requests]]
-uid = "4699"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4700.nm6R6YTnkmCo5evbykz4kz.toml

@@ -1,5 +0,0 @@
-internal = "Bump Bibo-Joshi/chango from 0.3.1 to 0.3.2"
-[[pull_requests]]
-uid = "4700"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4701.ah8Wi4SWc22EbgBc4KQeqH.toml

@@ -1,5 +0,0 @@
-internal = "Bump pypa/gh-action-pypi-publish from 1.12.3 to 1.12.4"
-[[pull_requests]]
-uid = "4701"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4709.dbwPVaU8vSacVkMLhiMjyJ.toml

@@ -1,5 +0,0 @@
-internal = "Bump pytest from 8.3.4 to 8.3.5"
-[[pull_requests]]
-uid = "4709"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4710.CSNixpvxJdLFaM6xSQ39Zf.toml

@@ -1,5 +0,0 @@
-internal = "Bump sphinx from 8.1.3 to 8.2.3"
-[[pull_requests]]
-uid = "4710"
-author_uid = "dependabot"
-closes_threads = []

changes/22.0_2025-03-15/4712.8ckkAPAXGzedityWEyv363.toml

@@ -1,5 +0,0 @@
-internal = "Bump Bibo-Joshi/chango from 0.3.2 to 0.4.0"
-[[pull_requests]]
-uid = "4712"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/22.0_2025-03-15/4719.d4xMztC8JjrbVgEscxvMWX.toml

@@ -1,5 +0,0 @@
-internal = "Bump Version to v22.0"
-[[pull_requests]]
-uid = "4719"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/22.1_2025-05-15/4692.dVZs28GuwTFnNJdWkvPbNv.toml

@@ -1,5 +0,0 @@
-breaking = "Drop backward compatibility for ``user_id`` in ``send_gift`` by updating the order of parameters. Please adapt your code accordingly or use keyword arguments."
-[[pull_requests]]
-uid = "4692"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/22.1_2025-05-15/4730.GsSUQSXzV8TF2Wav4CXRdd.toml

@@ -1,9 +0,0 @@
-documentation = "Documentation Improvements. Among others, add missing ``Returns`` field in ``User.get_profile_photos``"
-[[pull_requests]]
-uid = "4730"
-author_uid = "Bibo-Joshi"
-closes_threads = []
-[[pull_requests]]
-uid = "4740"
-author_uid = "aelkheir"
-closes_threads = []

changes/22.1_2025-05-15/4733.BRLwsEuh76974FPJRuiBjf.toml

@@ -1,5 +0,0 @@
-bugfixes = "Ensure execution of ``Bot.shutdown()`` even if ``Bot.get_me()`` fails in ``Bot.initialize()``"
-[[pull_requests]]
-uid = "4733"
-author_uid = "Poolitzer"
-closes_threads = []

changes/22.1_2025-05-15/4741.nVLBrFX4p8jTCBjMRqaYoQ.toml

@@ -1,5 +0,0 @@
-internal = "Bump codecov/test-results-action from 1.0.2 to 1.1.0"
-[[pull_requests]]
-uid = "4741"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4742.oEA6MjYXMafdbu2akWT5tC.toml

@@ -1,5 +0,0 @@
-internal = "Bump actions/setup-python from 5.4.0 to 5.5.0"
-[[pull_requests]]
-uid = "4742"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4743.SpMm4vvAMjEreykTcGwzcF.toml

@@ -1,5 +0,0 @@
-internal = "Bump github/codeql-action from 3.28.10 to 3.28.13"
-[[pull_requests]]
-uid = "4743"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4744.a4tsF64kZPA2noP7HtTzTX.toml

@@ -1,5 +0,0 @@
-internal = "Bump astral-sh/setup-uv from 5.3.1 to 5.4.1"
-[[pull_requests]]
-uid = "4744"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4745.emNmhxtvtTP9uLNQxpcVSj.toml

@@ -1,5 +0,0 @@
-internal = "Bump actions/download-artifact from 4.1.8 to 4.2.1"
-[[pull_requests]]
-uid = "4745"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4746.gWnX3BCxbvujQ8B2QejtTK.toml

@@ -1,5 +0,0 @@
-internal = "Reenable ``test_official`` Blocked by Debug Remnant"
-[[pull_requests]]
-uid = "4746"
-author_uid = "aelkheir"
-closes_threads = []

changes/22.1_2025-05-15/4747.MLmApvpGdwN7J24j7fXsDU.toml

@@ -1,5 +0,0 @@
-documentation = "Update ``AUTHORS.rst``, Adding `@aelkheir <https://github.com/aelkheir>`_ to Active Development Team"
-[[pull_requests]]
-uid = "4747"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/22.1_2025-05-15/4748.j3cKusZZKqTLbc542K4sqJ.toml

@@ -1,5 +0,0 @@
-internal = "Bump `pre-commit` Hooks to Latest Versions"
-[[pull_requests]]
-uid = "4748"
-author_uid = "pre-commit-ci"
-closes_threads = []

changes/22.1_2025-05-15/4756.JT5nmUmGRG6qDEh5ScMn5f.toml

@@ -1,51 +0,0 @@
-features = "Full Support for Bot API 9.0"
-deprecations = """This release comes with several deprecations, in line with our :ref:`stability policy <stability-policy>`.
-This includes the following:
-
-- Deprecated ``telegram.constants.StarTransactionsLimit.NANOSTAR_MIN_AMOUNT`` and ``telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT``. These members will be replaced by ``telegram.constants.NanostarLimit.MIN_AMOUNT`` and ``telegram.constants.NanostarLimit.MAX_AMOUNT``.
-- Deprecated the class ``telegram.constants.StarTransactions``. Its only member ``telegram.constants.StarTransactions.NANOSTAR_VALUE`` will be replaced by ``telegram.constants.Nanostar.VALUE``.
-- Bot API 9.0 deprecated ``BusinessConnection.can_reply`` in favor of ``BusinessConnection.rights``
-- Bot API 9.0 deprecated ``ChatFullInfo.can_send_gift`` in favor of ``ChatFullInfo.accepted_gift_types``.
-- Bot API 9.0 introduced these new required fields to existing classes:
-  - ``TransactionPartnerUser.transaction_type``
-  - ``ChatFullInfo.accepted_gift_types``
-
-  Passing these values as positional arguments is deprecated. We encourage you to use keyword arguments instead, as the the signature will be updated in a future release.
-
-These deprecations are backward compatible, but we strongly recommend to update your code to use the new members.
-"""
-[[pull_requests]]
-uid = "4756"
-author_uid = "Bibo-Joshi"
-closes_threads = ["4754"]
-[[pull_requests]]
-uid = "4757"
-author_uid = "Bibo-Joshi"
-closes_threads = []
-[[pull_requests]]
-uid = "4759"
-author_uid = "Bibo-Joshi"
-closes_threads = []
-[[pull_requests]]
-uid = "4763"
-author_uid = "aelkheir"
-closes_threads = []
-[[pull_requests]]
-uid = "4766"
-author_uid = "Bibo-Joshi"
-[[pull_requests]]
-uid = "4769"
-author_uid = "aelkheir"
-closes_threads = []
-[[pull_requests]]
-uid = "4773"
-author_uid = "aelkheir"
-closes_threads = []
-[[pull_requests]]
-uid = "4781"
-author_uid = "aelkheir"
-closes_threads = []
-[[pull_requests]]
-uid = "4782"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/22.1_2025-05-15/4758.dSyCdBJWEJroH2GynR2VaJ.toml

@@ -1,5 +0,0 @@
-internal = "Fine-tune ``chango`` and release workflows"
-[[pull_requests]]
-uid = "4758"
-author_uid = "Bibo-Joshi"
-closes_threads = ["4720"]

changes/22.1_2025-05-15/4761.mmsngFA6b4ccdEzEpFTZS3.toml

@@ -1,6 +0,0 @@
-bugfixes = "Fix Handling of ``Defaults`` for ``InputPaidMedia``"
-
-[[pull_requests]]
-uid = "4761"
-author_uid = "ngrogolev"
-closes_threads = ["4753"]

changes/22.1_2025-05-15/4762.PbcJGM8KPBMbKri3fdHKjh.toml

@@ -1,5 +0,0 @@
-documentation = "Clarify Documentation and Type Hints of ``InputMedia`` and ``InputPaidMedia``. Note that the ``media`` parameter accepts only objects of type ``str`` and ``InputFile``. The respective subclasses of ``Input(Paid)Media`` each accept a broader range of input type for the ``media`` parameter."
-[[pull_requests]]
-uid = "4762"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/22.1_2025-05-15/4775.kkLon84t7Vy5REKRe9LwPH.toml

@@ -1,5 +0,0 @@
-internal = "Bump codecov/codecov-action from 5.1.2 to 5.4.2"
-[[pull_requests]]
-uid = "4775"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4776.g83DxRk4WVWCC8rCd6ocFC.toml

@@ -1,5 +0,0 @@
-internal = "Bump actions/upload-artifact from 4.5.0 to 4.6.2"
-[[pull_requests]]
-uid = "4776"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4777.Lhgz8xFtQjgrKM2KvNfxwD.toml

@@ -1,5 +0,0 @@
-internal = "Bump stefanzweifel/git-auto-commit-action from 5.1.0 to 5.2.0"
-[[pull_requests]]
-uid = "4777"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4778.CeUSPNLbGGsqP2Vo4xKkdp.toml

@@ -1,5 +0,0 @@
-internal = "Bump github/codeql-action from 3.28.13 to 3.28.16"
-[[pull_requests]]
-uid = "4778"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4779.UqcbJVKYxwTtrBEGDgb3VS.toml

@@ -1,5 +0,0 @@
-internal = "Bump actions/download-artifact from 4.2.1 to 4.3.0"
-[[pull_requests]]
-uid = "4779"
-author_uid = "dependabot"
-closes_threads = []

changes/22.1_2025-05-15/4791.QycEvQbiaiJKraKDhAfFWM.toml

@@ -1,5 +0,0 @@
-other = "Bump Version to v22.1"
-[[pull_requests]]
-uid = "4791"
-author_uid = "Bibo-Joshi"
-closes_threads = []

changes/config.py

@@ -1,105 +0,0 @@
-# noqa: INP001
-# pylint: disable=import-error
-"""Configuration for the chango changelog tool"""
-
-import re
-from collections.abc import Collection
-from pathlib import Path
-from typing import Optional
-
-from chango import Version
-from chango.concrete import DirectoryChanGo, DirectoryVersionScanner, HeaderVersionHistory
-from chango.concrete.sections import GitHubSectionChangeNote, Section, SectionVersionNote
-
-version_scanner = DirectoryVersionScanner(base_directory=".", unreleased_directory="unreleased")
-
-
-class ChangoSectionChangeNote(
-    GitHubSectionChangeNote.with_sections(  # type: ignore[misc]
-        [
-            Section(uid="highlights", title="Highlights", sort_order=0),
-            Section(uid="breaking", title="Breaking Changes", sort_order=1),
-            Section(uid="security", title="Security Changes", sort_order=2),
-            Section(uid="deprecations", title="Deprecations", sort_order=3),
-            Section(uid="features", title="New Features", sort_order=4),
-            Section(uid="bugfixes", title="Bug Fixes", sort_order=5),
-            Section(uid="dependencies", title="Dependencies", sort_order=6),
-            Section(uid="other", title="Other Changes", sort_order=7),
-            Section(uid="documentation", title="Documentation", sort_order=8),
-            Section(uid="internal", title="Internal Changes", sort_order=9),
-        ]
-    )
-):
-    """Custom change note type for PTB. Mainly overrides get_sections to map labels to sections"""
-
-    OWNER = "python-telegram-bot"
-    REPOSITORY = "python-telegram-bot"
-
-    @classmethod
-    def get_sections(
-        cls,
-        labels: Collection[str],
-        issue_types: Optional[Collection[str]],
-    ) -> set[str]:
-        """Override get_sections to have customized auto-detection of relevant sections based on
-        the pull request and linked issues. Certainly not perfect in all cases, but should be a
-        good start for most PRs.
-        """
-        combined_labels = set(labels) | (set(issue_types or []))
-
-        mapping = {
-            "🐛 bug": "bugfixes",
-            "💡 feature": "features",
-            "🧹 chore": "internal",
-            "⚙️ bot-api": "features",
-            "⚙️ documentation": "documentation",
-            "⚙️ tests": "internal",
-            "⚙️ ci-cd": "internal",
-            "⚙️ security": "security",
-            "⚙️ examples": "documentation",
-            "⚙️ type-hinting": "other",
-            "🛠 refactor": "internal",
-            "🛠 breaking": "breaking",
-            "⚙️ dependencies": "dependencies",
-            "🔗 github-actions": "internal",
-            "🛠 code-quality": "internal",
-        }
-
-        # we want to return *all* from the mapping that are in the combined_labels
-        # removing superfluous sections from the fragment is a tad easier than adding them
-        found = {section for label, section in mapping.items() if label in combined_labels}
-
-        # if we have not found any sections, we default to "other"
-        return found or {"other"}
-
-
-class CustomChango(DirectoryChanGo):
-    """Custom ChanGo class for overriding release"""
-
-    def release(self, version: Version) -> bool:
-        """replace "14.5" with version.uid except in the contrib guide
-        then call super
-        """
-        root = Path(__file__).parent.parent / "telegram"
-        python_files = root.rglob("*.py")
-        pattern = re.compile(r"NEXT\.VERSION")
-        excluded_paths = {root / "docs/source/contribute.rst"}
-        for file_path in python_files:
-            if str(file_path) in excluded_paths:
-                continue
-
-            content = file_path.read_text(encoding="utf-8")
-            modified = pattern.sub(version.uid, content)
-
-            if content != modified:
-                file_path.write_text(modified, encoding="utf-8")
-
-        return super().release(version)
-
-
-chango_instance = CustomChango(
-    change_note_type=ChangoSectionChangeNote,
-    version_note_type=SectionVersionNote,
-    version_history_type=HeaderVersionHistory,
-    scanner=version_scanner,
-)

docs/Makefile

@@ -15,7 +15,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -j auto
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
@@ -56,8 +56,6 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-rebuild: clean html
-
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

docs/auxil/admonition_inserter.py

@@ -1,574 +0,0 @@
-#
-#  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2025
-#  Leandro Toledo de Souza <devs@python-telegram-bot.org>
-#
-#  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/].
-import collections.abc
-import contextlib
-import inspect
-import re
-import typing
-from collections import defaultdict
-from collections.abc import Iterator
-from socket import socket
-from types import FunctionType
-from typing import Union
-
-from apscheduler.job import Job as APSJob
-
-import telegram
-import telegram._utils.defaultvalue
-import telegram._utils.types
-import telegram.ext
-import telegram.ext._utils.types
-from tests.auxil.slots import mro_slots
-
-# Define the namespace for type resolution. This helps dealing with the internal imports that
-# we do in many places
-# The .copy() is important to avoid modifying the original namespace
-TG_NAMESPACE = vars(telegram).copy()
-TG_NAMESPACE.update(vars(telegram._utils.types))
-TG_NAMESPACE.update(vars(telegram._utils.defaultvalue))
-TG_NAMESPACE.update(vars(telegram.ext))
-TG_NAMESPACE.update(vars(telegram.ext._utils.types))
-TG_NAMESPACE.update(vars(telegram.ext._applicationbuilder))
-TG_NAMESPACE.update({"socket": socket, "APSJob": APSJob})
-
-
-class PublicMethod(typing.NamedTuple):
-    name: str
-    method: FunctionType
-
-
-def _is_inherited_method(cls: type, method_name: str) -> bool:
-    """Checks if a method is inherited from a parent class.
-    Inheritance is not considered if the parent class is private.
-    Recurses through all direcot or indirect parent classes.
-    """
-    # The [1:] slice is used to exclude the class itself from the MRO.
-    for base in cls.__mro__[1:]:
-        if method_name in base.__dict__ and not base.__name__.startswith("_"):
-            return True
-    return False
-
-
-def _iter_own_public_methods(cls: type) -> Iterator[PublicMethod]:
-    """Iterates over methods of a class that are not protected/private,
-    not camelCase and not inherited from the parent class.
-
-    Returns pairs of method names and methods.
-
-    This function is defined outside the class because it is used to create class constants.
-    """
-
-    # Use .isfunction() instead of .ismethod() because we want to include static methods.
-    for m in inspect.getmembers(cls, predicate=inspect.isfunction):
-        if (
-            not m[0].startswith("_")
-            and m[0].islower()  # to avoid camelCase methods
-            and not _is_inherited_method(cls, m[0])
-        ):
-            yield PublicMethod(m[0], m[1])
-
-
-class AdmonitionInserter:
-    """Class for inserting admonitions into docs of Telegram classes."""
-
-    CLASS_ADMONITION_TYPES = ("use_in", "available_in", "returned_in")
-    METHOD_ADMONITION_TYPES = ("shortcuts",)
-    ALL_ADMONITION_TYPES = CLASS_ADMONITION_TYPES + METHOD_ADMONITION_TYPES
-
-    FORWARD_REF_PATTERN = re.compile(r"^ForwardRef\('(?P<class_name>\w+)'\)$")
-    """ A pattern to find a class name in a ForwardRef typing annotation.
-    Class name (in a named group) is surrounded by parentheses and single quotes.
-    Note that since we're analyzing argument by argument, the pattern can be strict, with
-    start and end markers.
-    """
-
-    METHOD_NAMES_FOR_BOT_APP_APPBUILDER: typing.ClassVar[dict[type, str]] = {
-        cls: tuple(m.name for m in _iter_own_public_methods(cls))
-        for cls in (telegram.Bot, telegram.ext.ApplicationBuilder, telegram.ext.Application)
-    }
-    """A dictionary mapping Bot, Application & ApplicationBuilder classes to their relevant methods
-    that will
-    be mentioned in 'Returned in' and 'Use in' admonitions in other classes' docstrings.
-    Methods must be public, not aliases, not inherited from TelegramObject.
-    """
-
-    def __init__(self):
-        self.admonitions: dict[str, dict[Union[type, collections.abc.Callable], str]] = {
-            # dynamically determine which method to use to create a sub-dictionary
-            admonition_type: getattr(self, f"_create_{admonition_type}")()
-            for admonition_type in self.ALL_ADMONITION_TYPES
-        }
-        """Dictionary with admonitions. Contains sub-dictionaries, one per admonition type.
-        Each sub-dictionary matches bot methods (for "Shortcuts") or telegram classes (for other
-        admonition types) to texts of admonitions, e.g.:
-
-        ```
-        {
-            "use_in": {
-                <class 'telegram._chatinvitelink.ChatInviteLink'>:
-                    <"Use in" admonition for ChatInviteLink>,
-                ...
-            },
-            "available_in": {
-                <class 'telegram._chatinvitelink.ChatInviteLink'>:
-                    <"Available in" admonition">,
-                ...
-            },
-            "returned_in": {...}
-        }
-        ```
-        """
-
-    def insert_admonitions(
-        self,
-        obj: Union[type, collections.abc.Callable],
-        docstring_lines: list[str],
-    ):
-        """Inserts admonitions into docstring lines for a given class or method.
-
-        **Modifies lines in place**.
-        """
-        # A better way would be to copy the lines and return them, but that will not work with
-        # docs.auxil.sphinx_hooks.autodoc_process_docstring()
-
-        for admonition_type in self.ALL_ADMONITION_TYPES:
-            # If there is no admonition of the given type for the given class or method,
-            # continue to the next admonition type, maybe the class/method is listed there.
-            if obj not in self.admonitions[admonition_type]:
-                continue
-
-            insert_idx = self._find_insert_pos_for_admonition(docstring_lines)
-            admonition_lines = self.admonitions[admonition_type][obj].splitlines()
-
-            for idx in range(insert_idx, insert_idx + len(admonition_lines)):
-                docstring_lines.insert(idx, admonition_lines[idx - insert_idx])
-
-    def _create_available_in(self) -> dict[type, str]:
-        """Creates a dictionary with 'Available in' admonitions for classes that are available
-        in attributes of other classes.
-        """
-
-        # Generate a mapping of classes to ReST links to attributes in other classes that
-        # correspond to instances of a given class
-        # i.e. {telegram._files.sticker.Sticker: {":attr:`telegram.Message.sticker`", ...}}
-        attrs_for_class = defaultdict(set)
-
-        classes_to_inspect = inspect.getmembers(telegram, inspect.isclass) + inspect.getmembers(
-            telegram.ext, inspect.isclass
-        )
-
-        for _class_name, inspected_class in classes_to_inspect:
-            # We need to make "<class 'telegram._files.sticker.StickerSet'>" into
-            # "telegram.StickerSet" because that's the way the classes are mentioned in
-            # docstrings.
-            name_of_inspected_class_in_docstr = self._generate_class_name_for_link(inspected_class)
-
-            # Writing to dictionary: matching the class found in the type hint
-            # and its subclasses to the attribute of the class being inspected.
-            # The class in the attribute typehint (or its subclass) is the key,
-            # ReST link to attribute of the class currently being inspected is the value.
-
-            # best effort - args of __init__ means not all attributes are covered, but there is no
-            # other way to get type hints of all attributes, other than doing ast parsing maybe.
-            # (Docstring parsing was discontinued with the closing of #4414)
-            type_hints = typing.get_type_hints(inspected_class.__init__, localns=TG_NAMESPACE)
-            class_attrs = [slot for slot in mro_slots(inspected_class) if not slot.startswith("_")]
-            for target_attr in class_attrs:
-                try:
-                    self._resolve_arg_and_add_link(
-                        dict_of_methods_for_class=attrs_for_class,
-                        link=f":attr:`{name_of_inspected_class_in_docstr}.{target_attr}`",
-                        type_hints={target_attr: type_hints.get(target_attr)},
-                        resolve_nested_type_vars=False,
-                    )
-                except NotImplementedError as e:
-                    raise NotImplementedError(
-                        "Error generating Sphinx 'Available in' admonition "
-                        f"(admonition_inserter.py). Class {inspected_class} present in "
-                        f"attribute {target_attr} of class {name_of_inspected_class_in_docstr}"
-                        f" could not be resolved. {e!s}"
-                    ) from e
-
-            # Properties need to be parsed separately because they act like attributes but not
-            # listed as attributes.
-            properties = inspect.getmembers(inspected_class, lambda o: isinstance(o, property))
-            for prop_name, _ in properties:
-                # Make sure this property is really defined in the class being inspected.
-                # A property can be inherited from a parent class, then a link to it will not work.
-                if prop_name not in inspected_class.__dict__:
-                    continue
-
-                # fget is used to access the actual function under the property wrapper
-                type_hints = typing.get_type_hints(
-                    getattr(inspected_class, prop_name).fget, localns=TG_NAMESPACE
-                )
-
-                # Writing to dictionary: matching the class found in the docstring and its
-                # subclasses to the property of the class being inspected.
-                # The class in the property docstring (or its subclass) is the key,
-                # ReST link to property of the class currently being inspected is the value.
-                try:
-                    self._resolve_arg_and_add_link(
-                        dict_of_methods_for_class=attrs_for_class,
-                        link=f":attr:`{name_of_inspected_class_in_docstr}.{prop_name}`",
-                        type_hints={prop_name: type_hints.get("return")},
-                        resolve_nested_type_vars=False,
-                    )
-                except NotImplementedError as e:
-                    raise NotImplementedError(
-                        "Error generating Sphinx 'Available in' admonition "
-                        f"(admonition_inserter.py). Class {inspected_class} present in "
-                        f"property {prop_name} of class {name_of_inspected_class_in_docstr}"
-                        f" could not be resolved. {e!s}"
-                    ) from e
-
-        return self._generate_admonitions(attrs_for_class, admonition_type="available_in")
-
-    def _create_returned_in(self) -> dict[type, str]:
-        """Creates a dictionary with 'Returned in' admonitions for classes that are returned
-        in Bot's and ApplicationBuilder's methods.
-        """
-        # Generate a mapping of classes to ReST links to Bot methods which return it,
-        # i.e. {<class 'telegram._message.Message'>: {:meth:`telegram.Bot.send_message`, ...}}
-        methods_for_class = defaultdict(set)
-
-        for cls, method_names in self.METHOD_NAMES_FOR_BOT_APP_APPBUILDER.items():
-            for method_name in method_names:
-                method_link = self._generate_link_to_method(method_name, cls)
-                arg = getattr(cls, method_name)
-                ret_type_hint = typing.get_type_hints(arg, localns=TG_NAMESPACE)
-
-                try:
-                    self._resolve_arg_and_add_link(
-                        dict_of_methods_for_class=methods_for_class,
-                        link=method_link,
-                        type_hints={"return": ret_type_hint.get("return")},
-                        resolve_nested_type_vars=False,
-                    )
-                except NotImplementedError as e:
-                    raise NotImplementedError(
-                        "Error generating Sphinx 'Returned in' admonition "
-                        f"(admonition_inserter.py). {cls}, method {method_name}. "
-                        f"Couldn't resolve type hint in return annotation {ret_type_hint}. {e!s}"
-                    ) from e
-
-        return self._generate_admonitions(methods_for_class, admonition_type="returned_in")
-
-    def _create_shortcuts(self) -> dict[collections.abc.Callable, str]:
-        """Creates a dictionary with 'Shortcuts' admonitions for Bot methods that
-        have shortcuts in other classes.
-        """
-
-        # pattern for looking for calls to Bot methods only
-        bot_method_pattern = re.compile(
-            r"""\s*  # any number of whitespaces
-            (?<=return\sawait\sself\.get_bot\(\)\.)  # lookbehind
-            \w+  # the method name we are looking for, letters/underscores
-            (?=\() # lookahead: opening bracket before the args of the method start
-            """,
-            re.VERBOSE,
-        )
-
-        # Generate a mapping of methods of classes to links to Bot methods which they are shortcuts
-        # for, i.e. {<function Bot.send_voice at ...>: {:meth:`telegram.User.send_voice`, ...}
-        shortcuts_for_bot_method = defaultdict(set)
-
-        # inspect methods of all telegram classes for return statements that indicate
-        # that this given method is a shortcut for a Bot method
-        for _class_name, cls in inspect.getmembers(telegram, predicate=inspect.isclass):
-            if not cls.__module__.startswith("telegram"):
-                # For some reason inspect.getmembers() also yields some classes that are
-                # imported in the namespace but not part of the telegram module.
-                continue
-
-            if cls is telegram.Bot:
-                # no need to inspect Bot's own methods, as Bot can't have shortcuts in Bot
-                continue
-
-            for method_name, method in _iter_own_public_methods(cls):
-                # .getsourcelines() returns a tuple. Item [1] is an int
-                for line in inspect.getsourcelines(method)[0]:
-                    if not (bot_method_match := bot_method_pattern.search(line)):
-                        continue
-
-                    bot_method = getattr(telegram.Bot, bot_method_match.group())
-                    link_to_shortcut_method = self._generate_link_to_method(method_name, cls)
-                    shortcuts_for_bot_method[bot_method].add(link_to_shortcut_method)
-
-        return self._generate_admonitions(shortcuts_for_bot_method, admonition_type="shortcuts")
-
-    def _create_use_in(self) -> dict[type, str]:
-        """Creates a dictionary with 'Use in' admonitions for classes whose instances are
-        accepted as arguments for Bot's and ApplicationBuilder's methods.
-        """
-
-        # Generate a mapping of classes to links to Bot methods which accept them as arguments,
-        # i.e. {<class 'telegram._inline.inlinequeryresult.InlineQueryResult'>:
-        # {:meth:`telegram.Bot.answer_inline_query`, ...}}
-        methods_for_class = defaultdict(set)
-
-        for cls, method_names in self.METHOD_NAMES_FOR_BOT_APP_APPBUILDER.items():
-            for method_name in method_names:
-                method_link = self._generate_link_to_method(method_name, cls)
-
-                arg = getattr(cls, method_name)
-                param_type_hints = typing.get_type_hints(arg, localns=TG_NAMESPACE)
-                param_type_hints.pop("return", None)
-                try:
-                    self._resolve_arg_and_add_link(
-                        dict_of_methods_for_class=methods_for_class,
-                        link=method_link,
-                        type_hints=param_type_hints,
-                    )
-                except NotImplementedError as e:
-                    raise NotImplementedError(
-                        "Error generating Sphinx 'Use in' admonition "
-                        f"(admonition_inserter.py). {cls}, method {method_name}, parameter "
-                    ) from e
-
-        return self._generate_admonitions(methods_for_class, admonition_type="use_in")
-
-    @staticmethod
-    def _find_insert_pos_for_admonition(lines: list[str]) -> int:
-        """Finds the correct position to insert the class admonition and returns the index.
-
-        The admonition will be insert above "See also", "Examples:", version added/changed notes
-        and args, whatever comes first.
-
-        If no key phrases are found, the admonition will be inserted at the very end.
-        """
-        for idx, value in list(enumerate(lines)):
-            if value.startswith(
-                (
-                    # ".. seealso:",
-                    # The docstring contains heading "Examples:", but Sphinx will have it converted
-                    # to ".. admonition: Examples":
-                    ".. admonition:: Examples",
-                    ".. version",
-                    "Args:",
-                    # The space after ":param" is important because docstring can contain
-                    # ":paramref:" in its plain text in the beginning of a line (e.g. ExtBot):
-                    ":param ",
-                    # some classes (like "Credentials") have no params, so insert before attrs:
-                    ".. attribute::",
-                )
-            ):
-                return idx
-        return len(lines) - 1
-
-    def _generate_admonitions(
-        self,
-        attrs_or_methods_for_class: dict[type, set[str]],
-        admonition_type: str,
-    ) -> dict[type, str]:
-        """Generates admonitions of a given type.
-        Takes a dictionary of classes matched to ReST links to methods or attributes, e.g.:
-
-        ```
-        {<class 'telegram._files.sticker.StickerSet'>:
-        [":meth: `telegram.Bot.get_sticker_set`", ...]}.
-        ```
-
-        Returns a dictionary of classes matched to full admonitions, e.g.
-        for `admonition_type` "returned_in" (note that title and CSS class are generated
-        automatically):
-
-        ```
-        {<class 'telegram._files.sticker.StickerSet'>:
-        ".. admonition:: Returned in:
-            :class: returned-in
-
-            :meth: `telegram.Bot.get_sticker_set`"}.
-        ```
-        """
-
-        if admonition_type not in self.ALL_ADMONITION_TYPES:
-            raise TypeError(f"Admonition type {admonition_type} not supported.")
-
-        admonition_for_class = {}
-
-        for cls, attrs in attrs_or_methods_for_class.items():
-            if cls is telegram.ext.ApplicationBuilder:
-                # ApplicationBuilder is only used in and returned from its own methods,
-                # so its page needs no admonitions.
-                continue
-
-            sorted_attrs = sorted(attrs)
-
-            # e.g. for admonition type "use_in" the title will be "Use in" and CSS class "use-in".
-            admonition = f"""
-
-.. admonition:: {admonition_type.title().replace("_", " ")}
-    :class: {admonition_type.replace("_", "-")}
-    """
-            if len(sorted_attrs) > 1:
-                for target_attr in sorted_attrs:
-                    admonition += "\n    * " + target_attr
-            else:
-                admonition += f"\n    {sorted_attrs[0]}"
-
-            admonition += "\n    "  # otherwise an unexpected unindent warning will be issued
-            admonition_for_class[cls] = admonition
-
-        return admonition_for_class
-
-    @staticmethod
-    def _generate_class_name_for_link(cls_: type) -> str:
-        """Generates class name that can be used in a ReST link."""
-
-        # Check for potential presence of ".ext.", we will need to keep it.
-        ext = ".ext" if ".ext." in str(cls_) else ""
-        return f"telegram{ext}.{cls_.__name__}"
-
-    def _generate_link_to_method(self, method_name: str, cls: type) -> str:
-        """Generates a ReST link to a method of a telegram class."""
-
-        return f":meth:`{self._generate_class_name_for_link(cls)}.{method_name}`"
-
-    @staticmethod
-    def _iter_subclasses(cls_: type) -> Iterator:
-        if not hasattr(cls_, "__subclasses__") or cls_ is telegram.TelegramObject:
-            return iter([])
-        return (
-            # exclude private classes
-            c
-            for c in cls_.__subclasses__()
-            if not str(c).split(".")[-1].startswith("_")
-        )
-
-    def _resolve_arg_and_add_link(
-        self,
-        dict_of_methods_for_class: defaultdict,
-        link: str,
-        type_hints: dict[str, type],
-        resolve_nested_type_vars: bool = True,
-    ) -> None:
-        """A helper method. Tries to resolve the arg into a valid class. In case of success,
-        adds the link (to a method, attribute, or property) for that class' and its subclasses'
-        sets of links in the dictionary of admonitions.
-
-        **Modifies dictionary in place.**
-        """
-        type_hints.pop("self", None)
-
-        for cls in self._resolve_arg(type_hints, resolve_nested_type_vars):
-            # When trying to resolve an argument from args or return annotation,
-            # the method _resolve_arg returns None if nothing could be resolved.
-            # Also, if class was resolved correctly, "telegram" will definitely be in its str().
-            if cls is None or "telegram" not in str(cls):
-                continue
-
-            dict_of_methods_for_class[cls].add(link)
-
-            for subclass in self._iter_subclasses(cls):
-                dict_of_methods_for_class[subclass].add(link)
-
-    def _resolve_arg(
-        self,
-        type_hints: dict[str, type],
-        resolve_nested_type_vars: bool,
-    ) -> list[type]:
-        """Analyzes an argument of a method and recursively yields classes that the argument
-        or its sub-arguments (in cases like Union[...]) belong to, if they can be resolved to
-        telegram or telegram.ext classes.
-
-        Args:
-            type_hints: A dictionary of argument names and their types.
-            resolve_nested_type_vars: If True, nested type variables (like Application[BT, …])
-                will be resolved to their actual classes. If False, only the outermost type
-                variable will be resolved. *Only* affects ptb classes, not built-in types.
-                Useful for checking the return type of methods, where nested type variables
-                are not really useful.
-
-        Raises `NotImplementedError`.
-        """
-
-        def _is_ptb_class(cls: type) -> bool:
-            if not hasattr(cls, "__module__"):
-                return False
-            return cls.__module__.startswith("telegram")
-
-        # will be edited in place
-        telegram_classes = set()
-
-        def recurse_type(type_, is_recursed_from_ptb_class: bool):
-            next_is_recursed_from_ptb_class = is_recursed_from_ptb_class or _is_ptb_class(type_)
-
-            if hasattr(type_, "__origin__"):  # For generic types like Union, List, etc.
-                # Make sure it's not a telegram.ext generic type (e.g. ContextTypes[...])
-                org = typing.get_origin(type_)
-                if "telegram.ext" in str(org):
-                    telegram_classes.add(org)
-
-                args = typing.get_args(type_)
-                for arg in args:
-                    recurse_type(arg, next_is_recursed_from_ptb_class)
-            elif isinstance(type_, typing.TypeVar) and (
-                resolve_nested_type_vars or not is_recursed_from_ptb_class
-            ):
-                # gets access to the "bound=..." parameter
-                recurse_type(type_.__bound__, next_is_recursed_from_ptb_class)
-            elif inspect.isclass(type_) and "telegram" in inspect.getmodule(type_).__name__:
-                telegram_classes.add(type_)
-            elif isinstance(type_, typing.ForwardRef):
-                # Resolving ForwardRef is not easy. https://peps.python.org/pep-0749/ will
-                # hopefully make it better by introducing typing.resolve_forward_ref() in py3.14
-                # but that's not there yet
-                # So for now we fall back to a best effort approach of guessing if the class is
-                # available in tg or tg.ext
-                with contextlib.suppress(AttributeError):
-                    telegram_classes.add(self._resolve_class(type_.__forward_arg__))
-
-        for type_hint in type_hints.values():
-            if type_hint is not None:
-                recurse_type(type_hint, False)
-
-        return list(telegram_classes)
-
-    @staticmethod
-    def _resolve_class(name: str) -> Union[type, None]:
-        """The keys in the admonitions dictionary are not strings like "telegram.StickerSet"
-        but classes like <class 'telegram._files.sticker.StickerSet'>.
-
-        This method attempts to resolve a PTB class from a name that does or does not
-        contain the word 'telegram', e.g.
-        <class 'telegram._files.sticker.StickerSet'> from "telegram.StickerSet" or "StickerSet".
-
-        Returns a class on success, :obj:`None` if nothing could be resolved.
-        """
-
-        for option in (
-            name,
-            f"telegram.{name}",
-            f"telegram.ext.{name}",
-            f"telegram.ext.filters.{name}",
-        ):
-            # NameError will be raised if trying to eval just name and it doesn't work, e.g.
-            # "Name 'ApplicationBuilder' is not defined".
-            # AttributeError will be raised if trying to e.g. eval f"telegram.{name}" when the
-            # class denoted by `name` actually belongs to `telegram.ext`:
-            # "module 'telegram' has no attribute 'ApplicationBuilder'".
-            # If neither option works, this is not a PTB class.
-            with contextlib.suppress(NameError, AttributeError):
-                return eval(option)
-        return None
-
-
-if __name__ == "__main__":
-    # just try instantiating for debugging purposes
-    AdmonitionInserter()

docs/auxil/kwargs_insertion.py

@@ -1,108 +0,0 @@
-#
-#  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2025
-#  Leandro Toledo de Souza <devs@python-telegram-bot.org>
-#
-#  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/].
-import inspect
-
-keyword_args = [
-    "Keyword Arguments:",
-    (
-        "    read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
-        "        :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to "
-        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`. "
-    ),
-    (
-        "    write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
-        "        :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to "
-        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
-    ),
-    (
-        "    connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
-        "        :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to "
-        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
-    ),
-    (
-        "    pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
-        "        :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to "
-        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
-    ),
-    (
-        "    api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments"
-        "        to be passed to the Telegram API. See :meth:`~telegram.Bot.do_api_request` for"
-        "        limitations."
-    ),
-    "",
-]
-
-media_write_timeout_change_methods = [
-    "add_sticker_to_set",
-    "create_new_sticker_set",
-    "send_animation",
-    "send_audio",
-    "send_document",
-    "send_media_group",
-    "send_photo",
-    "send_sticker",
-    "send_video",
-    "send_video_note",
-    "send_voice",
-    "set_chat_photo",
-    "upload_sticker_file",
-]
-media_write_timeout_change = [
-    "    write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
-    "        :paramref:`telegram.request.BaseRequest.post.write_timeout`. By default, ``20`` "
-    "        seconds are used as write timeout."
-    "",
-    "",
-    "       .. versionchanged:: 22.0",
-    "           The default value changed to "
-    "           :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
-    "",
-    "",
-]
-get_updates_read_timeout_addition = [
-    "        :paramref:`timeout` will be added to this value.",
-    "",
-    "",
-    "        .. versionchanged:: 20.7",
-    "           Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE` instead of ",
-    "           ``2``.",
-]
-
-
-def find_insert_pos_for_kwargs(lines: list[str]) -> int:
-    """Finds the correct position to insert the keyword arguments and returns the index."""
-    for idx, value in reversed(list(enumerate(lines))):  # reversed since :returns: is at the end
-        if value.startswith("Returns"):
-            return idx
-    return False
-
-
-def check_timeout_and_api_kwargs_presence(obj: object) -> int:
-    """Checks if the method has timeout and api_kwargs keyword only parameters."""
-    sig = inspect.signature(obj)
-    params_to_check = (
-        "read_timeout",
-        "write_timeout",
-        "connect_timeout",
-        "pool_timeout",
-        "api_kwargs",
-    )
-    return all(
-        param in sig.parameters and sig.parameters[param].kind == inspect.Parameter.KEYWORD_ONLY
-        for param in params_to_check
-    )

docs/auxil/link_code.py

@@ -1,78 +0,0 @@
-#
-#  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2025
-#  Leandro Toledo de Souza <devs@python-telegram-bot.org>
-#
-#  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/].
-"""Functionality in this file is used for getting the [source] links on the classes, methods etc
-to link to the correct files & lines on github. Can be simplified once
-https://github.com/sphinx-doc/sphinx/issues/1556 is closed
-"""
-import subprocess
-from pathlib import Path
-
-from sphinx.util import logging
-
-# get the sphinx(!) logger
-# Makes sure logs render in red and also plays nicely with e.g. the `nitpicky` option.
-sphinx_logger = logging.getLogger(__name__)
-
-
-# must be a module-level variable so that it can be written to by the `autodoc-process-docstring`
-# event handler in `sphinx_hooks.py`
-LINE_NUMBERS: dict[str, tuple[Path, int, int]] = {}
-
-
-def _git_branch() -> str:
-    """Get's the current git sha if available or fall back to `master`"""
-    try:
-        output = subprocess.check_output(
-            ["git", "describe", "--tags", "--always"], stderr=subprocess.STDOUT
-        )
-        return output.decode().strip()
-    except Exception as exc:
-        sphinx_logger.exception(
-            "Failed to get a description of the current commit. Falling back to `master`.",
-            exc_info=exc,
-        )
-        return "master"
-
-
-git_branch = _git_branch()
-base_url = "https://github.com/python-telegram-bot/python-telegram-bot/blob/"
-
-
-def linkcode_resolve(_, info) -> str:
-    """See www.sphinx-doc.org/en/master/usage/extensions/linkcode.html"""
-    combined = ".".join((info["module"], info["fullname"]))
-    # special casing for ExtBot which is due to the special structure of extbot.rst
-    combined = combined.replace("ExtBot.ExtBot", "ExtBot")
-
-    line_info = LINE_NUMBERS.get(combined)
-
-    if not line_info:
-        # Try the __init__
-        line_info = LINE_NUMBERS.get(f"{combined.rsplit('.', 1)[0]}.__init__")
-    if not line_info:
-        # Try the class
-        line_info = LINE_NUMBERS.get(f"{combined.rsplit('.', 1)[0]}")
-    if not line_info:
-        # Try the module
-        line_info = LINE_NUMBERS.get(info["module"])
-
-    if not line_info:
-        return None
-
-    file, start_line, end_line = line_info
-    return f"{base_url}{git_branch}/{file}#L{start_line}-L{end_line}"

docs/auxil/sphinx_hooks.py

@@ -1,224 +0,0 @@
-#
-#  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2025
-#  Leandro Toledo de Souza <devs@python-telegram-bot.org>
-#
-#  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/].
-import contextlib
-import inspect
-import re
-import typing
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from sphinx.application import Sphinx
-
-import telegram
-import telegram.ext
-from docs.auxil.admonition_inserter import AdmonitionInserter
-from docs.auxil.kwargs_insertion import (
-    check_timeout_and_api_kwargs_presence,
-    find_insert_pos_for_kwargs,
-    get_updates_read_timeout_addition,
-    keyword_args,
-    media_write_timeout_change,
-    media_write_timeout_change_methods,
-)
-from docs.auxil.link_code import LINE_NUMBERS
-
-if TYPE_CHECKING:
-    import collections.abc
-
-
-ADMONITION_INSERTER = AdmonitionInserter()
-
-# Some base classes are implementation detail
-# We want to instead show *their* base class
-PRIVATE_BASE_CLASSES = {
-    "_ChatUserBaseFilter": "MessageFilter",
-    "_Dice": "MessageFilter",
-    "_BaseThumbedMedium": "TelegramObject",
-    "_BaseMedium": "TelegramObject",
-    "_CredentialsBase": "TelegramObject",
-    "_ChatBase": "TelegramObject",
-}
-
-
-FILE_ROOT = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
-
-
-def autodoc_skip_member(app, what, name, obj, skip, options):
-    """We use this to not document certain members like filter() or check_update() for filters.
-    See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members"""
-
-    included = {"MessageFilter", "UpdateFilter"}  # filter() and check_update() only for these.
-    included_in_obj = any(inc in repr(obj) for inc in included)
-
-    if included_in_obj:  # it's difficult to see if check_update is from an inherited-member or not
-        for frame in inspect.stack():  # From https://github.com/sphinx-doc/sphinx/issues/9533
-            if frame.function == "filter_members":
-                docobj = frame.frame.f_locals["self"].object
-                if not any(inc in str(docobj) for inc in included) and name == "check_update":
-                    return True
-                break
-
-    if name == "filter" and obj.__module__ == "telegram.ext.filters" and not included_in_obj:
-        return True  # return True to exclude from docs.
-    return None
-
-
-def autodoc_process_docstring(
-    app: Sphinx, what, name: str, obj: object, options, lines: list[str]
-):
-    """We do the following things:
-    1) Use this method to automatically insert the Keyword Args and "Shortcuts" admonitions
-       for the Bot methods.
-
-    2) Use this method to automatically insert "Returned in" admonition into classes
-       that are returned from the Bot methods
-
-    3) Use this method to automatically insert "Available in" admonition into classes
-       whose instances are available as attributes of other classes
-
-    4) Use this method to automatically insert "Use in" admonition into classes
-       whose instances can be used as arguments of the Bot methods
-
-    5) Misuse this autodoc hook to get the file names & line numbers because we have access
-       to the actual object here.
-    """
-
-    # 1) Insert the Keyword Args and "Shortcuts" admonitions for the Bot methods
-    method_name = name.split(".")[-1]
-    if (
-        name.startswith("telegram.Bot.")
-        and what == "method"
-        and method_name.islower()
-        and check_timeout_and_api_kwargs_presence(obj)
-    ):
-        insert_index = find_insert_pos_for_kwargs(lines)
-        if not insert_index:
-            raise ValueError(
-                f"Couldn't find the correct position to insert the keyword args for {obj}."
-            )
-
-        get_updates: bool = method_name == "get_updates"
-        # The below can be done in 1 line with itertools.chain, but this must be modified in-place
-        insert_idx = insert_index
-        for i in range(insert_index, insert_index + len(keyword_args)):
-            to_insert = keyword_args[i - insert_index]
-
-            if (
-                "post.write_timeout`. Defaults to" in to_insert
-                and method_name in media_write_timeout_change_methods
-            ):
-                effective_insert: list[str] = media_write_timeout_change
-            elif get_updates and to_insert.lstrip().startswith("read_timeout"):
-                effective_insert = [to_insert, *get_updates_read_timeout_addition]
-            else:
-                effective_insert = [to_insert]
-
-            lines[insert_idx:insert_idx] = effective_insert
-            insert_idx += len(effective_insert)
-
-        ADMONITION_INSERTER.insert_admonitions(
-            obj=typing.cast("collections.abc.Callable", obj),
-            docstring_lines=lines,
-        )
-
-    # 2-4) Insert "Returned in", "Available in", "Use in" admonitions into classes
-    # (where applicable)
-    if what == "class":
-        ADMONITION_INSERTER.insert_admonitions(
-            obj=typing.cast("type", obj),  # since "what" == class, we know it's not just object
-            docstring_lines=lines,
-        )
-
-    # 5) Get the file names & line numbers
-    # We can't properly handle ordinary attributes.
-    # In linkcode_resolve we'll resolve to the `__init__` or module instead
-    if what == "attribute":
-        return
-
-    # Special casing for properties
-    if hasattr(obj, "fget"):
-        obj = obj.fget
-
-    # Special casing for filters
-    if isinstance(obj, telegram.ext.filters.BaseFilter):
-        obj = obj.__class__
-
-    with contextlib.suppress(Exception):
-        source_lines, start_line = inspect.getsourcelines(obj)
-        end_line = start_line + len(source_lines)
-        file = Path(inspect.getsourcefile(obj)).relative_to(FILE_ROOT)
-        LINE_NUMBERS[name] = (file, start_line, end_line)
-
-    # Since we don't document the `__init__`, we call this manually to have it available for
-    # attributes -- see the note above
-    if what == "class":
-        autodoc_process_docstring(app, "method", f"{name}.__init__", obj.__init__, options, lines)
-
-
-def autodoc_process_bases(app, name, obj, option, bases: list) -> None:
-    """Here we fine tune how the base class's classes are displayed."""
-    for idx, raw_base in enumerate(bases):
-        # let's use a string representation of the object
-        base = str(raw_base)
-
-        # Special case for abstract context managers which are wrongly resoled for some reason
-        if base.startswith("typing.AbstractAsyncContextManager"):
-            bases[idx] = ":class:`contextlib.AbstractAsyncContextManager`"
-            continue
-
-        # Special case because base classes are in std lib:
-        if "StringEnum" in base == "<enum 'StringEnum'>":
-            bases[idx] = ":class:`enum.Enum`"
-            bases.insert(0, ":class:`str`")
-            continue
-
-        if "IntEnum" in base:
-            bases[idx] = ":class:`enum.IntEnum`"
-            continue
-
-        if "FloatEnum" in base:
-            bases[idx] = ":class:`enum.Enum`"
-            bases.insert(0, ":class:`float`")
-            continue
-
-        # Drop generics (at least for now)
-        if base.endswith("]"):
-            base = base.split("[", maxsplit=1)[0]
-            bases[idx] = f":class:`{base}`"
-
-        # Now convert `telegram._message.Message` to `telegram.Message` etc
-        if (
-            not (match := re.search(pattern=r"(telegram(\.ext|))\.[_\w\.]+", string=base))
-            or "_utils" in base
-        ):
-            continue
-
-        parts = match.group(0).split(".")
-
-        # Remove private paths
-        for index, part in enumerate(parts):
-            if part.startswith("_"):
-                parts = parts[:index] + parts[-1:]
-                break
-
-        # Replace private base classes with their respective parent
-        parts = [PRIVATE_BASE_CLASSES.get(part, part) for part in parts]
-
-        base = ".".join(parts)
-
-        bases[idx] = f":class:`{base}`"

docs/auxil/tg_const_role.py

@@ -1,101 +0,0 @@
-#
-#  A library that provides a Python interface to the Telegram Bot API
-#  Copyright (C) 2015-2025
-#  Leandro Toledo de Souza <devs@python-telegram-bot.org>
-#
-#  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/].
-import datetime as dtm
-from enum import Enum
-
-from docutils.nodes import Element
-from sphinx.domains.python import PyXRefRole
-from sphinx.environment import BuildEnvironment
-from sphinx.util import logging
-
-import telegram
-
-# get the sphinx(!) logger
-# Makes sure logs render in red and also plays nicely with e.g. the `nitpicky` option.
-sphinx_logger = logging.getLogger(__name__)
-
-CONSTANTS_ROLE = "tg-const"
-
-
-class TGConstXRefRole(PyXRefRole):
-    """This is a bit of Sphinx magic. We add a new role type called tg-const that allows us to
-    reference values from the `telegram.constants.module` while using the actual value as title
-    of the link.
-
-    Example:
-
-        :tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` renders as `4096` but links to
-        the constant.
-    """
-
-    def process_link(
-        self,
-        env: BuildEnvironment,
-        refnode: Element,
-        has_explicit_title: bool,
-        title: str,
-        target: str,
-    ) -> tuple[str, str]:
-        title, target = super().process_link(env, refnode, has_explicit_title, title, target)
-        try:
-            # We use `eval` to get the value of the expression. Maybe there are better ways to
-            # do this via importlib or so, but it does the job for now
-            value = eval(target)
-            # Maybe we need a better check if the target is actually from tg.constants
-            # for now checking if it's an Enum suffices since those are used nowhere else in PTB
-            if isinstance(value, Enum):
-                # Special casing for file size limits
-                if isinstance(value, telegram.constants.FileSizeLimit):
-                    return f"{int(value.value / 1e6)} MB", target
-                return repr(value.value), target
-            # Just for (Bot API) versions number auto add in constants:
-            if isinstance(value, str) and target in (
-                "telegram.constants.BOT_API_VERSION",
-                "telegram.__version__",
-            ):
-                return value, target
-            if isinstance(value, tuple) and target in (
-                "telegram.constants.BOT_API_VERSION_INFO",
-                "telegram.__version_info__",
-            ):
-                return str(value), target
-            if (
-                isinstance(value, dtm.datetime)
-                and value == telegram.constants.ZERO_DATE
-                and target in ("telegram.constants.ZERO_DATE",)
-            ):
-                return repr(value), target
-            sphinx_logger.warning(
-                "%s:%d: WARNING: Did not convert reference %s. :%s: is not supposed"
-                " to be used with this type of target.",
-                refnode.source,
-                refnode.line,
-                refnode.rawsource,
-                CONSTANTS_ROLE,
-            )
-        except Exception as exc:
-            sphinx_logger.exception(
-                "%s:%d: WARNING: Did not convert reference %s due to an exception.",
-                refnode.source,
-                refnode.line,
-                refnode.rawsource,
-                exc_info=exc,
-            )
-            return title, target
-        else:
-            return title, target

docs/requirements-docs.txt

@@ -1,10 +1,6 @@
-chango~=0.4.0
-sphinx==8.2.3
-furo==2024.8.6
-furo-sphinx-search @ git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
-sphinx-paramlinks==0.6.0
-sphinxcontrib-mermaid==1.0.0
-sphinx-copybutton==0.5.2
-sphinx-inline-tabs==2023.4.21
-# Temporary. See #4387
-sphinx-build-compatibility @ git+https://github.com/readthedocs/sphinx-build-compatibility.git@58aabc5f207c6c2421f23d3578adc0b14af57047
+sphinx==3.5.4
+sphinx-pypi-upload
+# When bumping this, make sure to rebuild the dark-mode CSS
+# More instructions at source/_static/dark.css
+# Ofc once https://github.com/readthedocs/sphinx_rtd_theme/issues/224 is closed, we should use that
+sphinx_rtd_theme==0.5.2

docs/source/_static/style_admonitions.css

@@ -1,65 +0,0 @@
-:root {
-  --icon--shortcuts: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-signpost' viewBox='0 0 16 16'%3E%3Cpath d='M7 1.414V4H2a1 1 0 0 0-1 1v4a1 1 0 0 0 1 1h5v6h2v-6h3.532a1 1 0 0 0 .768-.36l1.933-2.32a.5.5 0 0 0 0-.64L13.3 4.36a1 1 0 0 0-.768-.36H9V1.414a1 1 0 0 0-2 0zM12.532 5l1.666 2-1.666 2H2V5h10.532z'/%3E%3C/svg%3E");
-  --icon--returned-in: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-arrow-return-right' viewBox='0 0 16 16'%3E%3Cpath fill-rule='evenodd' d='M1.5 1.5A.5.5 0 0 0 1 2v4.8a2.5 2.5 0 0 0 2.5 2.5h9.793l-3.347 3.346a.5.5 0 0 0 .708.708l4.2-4.2a.5.5 0 0 0 0-.708l-4-4a.5.5 0 0 0-.708.708L13.293 8.3H3.5A1.5 1.5 0 0 1 2 6.8V2a.5.5 0 0 0-.5-.5z'/%3E%3C/svg%3E");
-  --icon--available-in: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-geo-fill' viewBox='0 0 16 16'%3E%3Cpath fill-rule='evenodd' d='M4 4a4 4 0 1 1 4.5 3.969V13.5a.5.5 0 0 1-1 0V7.97A4 4 0 0 1 4 3.999zm2.493 8.574a.5.5 0 0 1-.411.575c-.712.118-1.28.295-1.655.493a1.319 1.319 0 0 0-.37.265.301.301 0 0 0-.057.09V14l.002.008a.147.147 0 0 0 .016.033.617.617 0 0 0 .145.15c.165.13.435.27.813.395.751.25 1.82.414 3.024.414s2.273-.163 3.024-.414c.378-.126.648-.265.813-.395a.619.619 0 0 0 .146-.15.148.148 0 0 0 .015-.033L12 14v-.004a.301.301 0 0 0-.057-.09 1.318 1.318 0 0 0-.37-.264c-.376-.198-.943-.375-1.655-.493a.5.5 0 1 1 .164-.986c.77.127 1.452.328 1.957.594C12.5 13 13 13.4 13 14c0 .426-.26.752-.544.977-.29.228-.68.413-1.116.558-.878.293-2.059.465-3.34.465-1.281 0-2.462-.172-3.34-.465-.436-.145-.826-.33-1.116-.558C3.26 14.752 3 14.426 3 14c0-.599.5-1 .961-1.243.505-.266 1.187-.467 1.957-.594a.5.5 0 0 1 .575.411z'/%3E%3C/svg%3E");
-  --icon--use-in:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-funnel' viewBox='0 0 16 16'%3E%3Cpath d='M1.5 1.5A.5.5 0 0 1 2 1h12a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-.128.334L10 8.692V13.5a.5.5 0 0 1-.342.474l-3 1A.5.5 0 0 1 6 14.5V8.692L1.628 3.834A.5.5 0 0 1 1.5 3.5v-2zm1 .5v1.308l4.372 4.858A.5.5 0 0 1 7 8.5v5.306l2-.666V8.5a.5.5 0 0 1 .128-.334L13.5 3.308V2h-11z'/%3E%3C/svg%3E");
-}
-.admonition.shortcuts {
-  border-color: rgb(43, 155, 70);
-}
-.admonition.shortcuts > .admonition-title {
-  background-color: rgba(43, 155, 70, 0.1);
-  border-color: rgb(43, 155, 70);
-}
-.admonition.shortcuts > .admonition-title::before {
-  background-color: rgb(43, 155, 70);
-  -webkit-mask-image: var(--icon--shortcuts);
-  mask-image: var(--icon--shortcuts);
-}
-
-.admonition.returned-in {
-  border-color: rgb(230, 109, 15);
-}
-.admonition.returned-in > .admonition-title {
-  background-color: rgba(177, 108, 51, 0.1);
-  border-color: rgb(230, 109, 15);
-}
-.admonition.returned-in > .admonition-title::before {
-  background-color: rgb(230, 109, 15);
-  -webkit-mask-image: var(--icon--returned-in);
-  mask-image: var(--icon--returned-in);
-}
-
-.admonition.available-in {
-  border-color: rgb(183, 4, 215);
-}
-.admonition.available-in > .admonition-title {
-  background-color: rgba(165, 99, 177, 0.1);
-  border-color: rgb(183, 4, 215);
-}
-.admonition.available-in > .admonition-title::before {
-  background-color: rgb(183, 4, 215);
-  -webkit-mask-image: var(--icon--available-in);
-  mask-image: var(--icon--available-in);
-}
-
-.admonition.use-in {
-  border-color: rgb(203, 147, 1);
-}
-.admonition.use-in > .admonition-title {
-  background-color: rgba(176, 144, 60, 0.1);
-  border-color: rgb(203, 147, 1);
-}
-.admonition.use-in > .admonition-title::before {
-  background-color: rgb(203, 147, 1);
-  -webkit-mask-image: var(--icon--use-in);
-  mask-image: var(--icon--use-in);
-}
-
-.admonition.returned-in > ul:hover, .admonition.available-in > ul:hover, .admonition.use-in > ul:hover, .admonition.shortcuts > ul:hover {
-  cursor: move;
-}
-.admonition.returned-in > ul, .admonition.available-in > ul, .admonition.use-in > ul, .admonition.shortcuts > ul {
-  max-height: 200px;
-  overflow-y: auto;
-}

docs/source/_static/style_external_link.css

@@ -1,5 +0,0 @@
-article a.reference.external:not([href*="/python-telegram-bot/blob/"])::after {
-      content: url('data:image/svg+xml,<svg width="12" height="12" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke-width="1.5" stroke="%23607D8B" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z"/><path d="M11 7h-5a2 2 0 0 0 -2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2 -2v-5" /><line x1="10" y1="14" x2="20" y2="4" /><polyline points="15 4 20 4 20 9" /></svg>');
-      margin: 0 0.25rem;
-      vertical-align: middle;
-}

docs/source/_static/style_general.css

@@ -1,3 +0,0 @@
-.article-container h1 {
-      overflow-wrap: anywhere;
-}

docs/source/_static/style_images.css

@@ -1,15 +0,0 @@
-figure > img {
-    height: 300px;  /* resize figures so they aren't too big */
-}
-
-@media (prefers-color-scheme: dark) {
-    body:not([data-theme="light"]) figure > img {  /* auto and dark is dark mode */
-        filter: invert(92%);
-    }
-}
-
-@media (prefers-color-scheme: light) {
-    body[data-theme="dark"] figure > img {  /* auto and light is light mode */
-        filter: invert(92%);
-    }
-}

docs/source/_static/style_mermaid_diagrams.css

@@ -1,3 +0,0 @@
-.mermaid svg {
-  height: auto;
-}

docs/source/_static/style_sidebar_brand.css

@@ -1,11 +0,0 @@
-.sidebar-sticky .sidebar-brand {
-      flex-direction: row;
-}
-
-.sidebar-sticky .sidebar-brand .sidebar-logo-container {
-      align-self: center;
-}
-
-.sidebar-sticky .sidebar-brand .sidebar-brand-text {
-      align-self: center;
-}

docs/source/changelog.rst

@@ -1,9 +1 @@
-.. _ptb-changelog:
-
-=========
-Changelog
-=========
-
-.. chango::
-
-.. include:: ../../changes/LEGACY.rst
+.. include:: ../../CHANGES.rst

docs/source/coc.rst

@@ -1 +0,0 @@
-.. include:: ../../CODE_OF_CONDUCT.rst

docs/source/conf.py

@@ -1,319 +1,274 @@
-import os
-import re
+# -*- coding: utf-8 -*-
+#
+# Python Telegram Bot documentation build configuration file, created by
+# sphinx-quickstart on Mon Aug 10 22:25:07 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
 import sys
-from pathlib import Path
+import os
+# import telegram
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-from sphinx.application import Sphinx
-
-if sys.version_info < (3, 12):
-    # Due to dependency on chango
-    raise RuntimeError("This documentation needs at least Python 3.12")
-
-
-sys.path.insert(0, str(Path("../..").resolve().absolute()))
+sys.path.insert(0, os.path.abspath('../..'))
 
 # -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '3.5.2'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon'
+]
+# Don't show type hints in the signature - that just makes it hardly readable
+# and we document the types anyway
+autodoc_typehints = 'none'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
 # General information about the project.
-project = "python-telegram-bot"
-copyright = "2015-2025, Leandro Toledo"
-author = "Leandro Toledo"
+project = u'python-telegram-bot'
+copyright = u'2015-2021, Leandro Toledo'
+author = u'Leandro Toledo'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-
-# Import needs to be below the sys.path.insert above
-import telegram  # noqa: E402
-
-version = telegram.__version__
+version = '13.13'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = telegram.__version__
+release = '13.13'  # telegram.__version__
 
-# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "8.1.3"
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "chango.sphinx_ext",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.linkcode",
-    "sphinx.ext.extlinks",
-    "sphinx_paramlinks",
-    "sphinx_copybutton",
-    "sphinx_inline_tabs",
-    "sphinxcontrib.mermaid",
-    "sphinx_search.extension",
-]
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
 
-# Temporary. See #4387
-if os.environ.get("READTHEDOCS", "") == "True":
-    extensions.append("sphinx_build_compatibility.extension")
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
 
-# Configuration for the chango sphinx directive
-chango_pyproject_toml_path = Path(__file__).parent.parent.parent
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
 
-# For shorter links to Wiki in docstrings
-extlinks = {
-    "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"),
-    "pr": ("https://github.com/python-telegram-bot/python-telegram-bot/pull/%s", "#%s"),
-    "issue": ("https://github.com/python-telegram-bot/python-telegram-bot/issues/%s", "#%s"),
-}
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
 
-# Use intersphinx to reference the python builtin library docs
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
-    "APScheduler": ("https://apscheduler.readthedocs.io/en/3.x/", None),
-}
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-source_suffix = ".rst"
-
-# The master toctree document.
-master_doc = "index"
-
-# Global substitutions
-rst_prolog = ""
-for file in Path.cwd().glob("../substitutions/*.rst"):
-    rst_prolog += "\n" + file.read_text(encoding="utf-8")
-
-# -- Extension settings ------------------------------------------------
-napoleon_use_admonition_for_examples = True
-
-# Don't show type hints in the signature - that just makes it hardly readable
-# and we document the types anyway
-autodoc_typehints = "none"
-
-# Show docstring for special members
-autodoc_default_options = {
-    "special-members": True,
-    # For some reason, __weakref__ can not be ignored by using "inherited-members" in all cases
-    # so we list it here.
-    "exclude-members": "__init__, __weakref__",
-}
-
-# Fail on warnings & unresolved references etc
-nitpicky = True
-
-# Paramlink style
-paramlinks_hyperlink_param = "name"
-
-# Linkcheck settings
-linkcheck_ignore = [
-    # Let's not check issue/PR links - that's wasted resources
-    r"http(s)://github\.com/python-telegram-bot/python-telegram-bot/(issues|pull)/\d+/?",
-    # For some reason linkcheck has a problem with these two:
-    re.escape("https://github.com/python-telegram-bot/python-telegram-bot/discussions/new"),
-    re.escape("https://github.com/python-telegram-bot/python-telegram-bot/issues/new"),
-    # Anchors are apparently inserted by GitHub dynamically, so let's skip checking them
-    "https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples#",
-    r"https://github\.com/python-telegram-bot/python-telegram-bot/wiki/[\w\-_,]+\#",
-    # The LGPL license link regularly causes network errors for some reason
-    re.escape("https://www.gnu.org/licenses/lgpl-3.0.html"),
-    # The doc-fixes branch may not always exist - doesn't matter, we only link to it from the
-    # contributing guide
-    re.escape("https://docs.python-telegram-bot.org/en/doc-fixes"),
-    # Apparently has some human-verification check and gives 403 in the sphinx build
-    re.escape("https://stackoverflow.com/questions/tagged/python-telegram-bot"),
-]
-linkcheck_allowed_redirects = {
-    # Redirects to the default version are okay
-    r"https://docs\.python-telegram-bot\.org/.*": (
-        r"https://docs\.python-telegram-bot\.org/en/[\w\d\.]+/.*"
-    ),
-    # pre-commit.ci always redirects to the latest run
-    re.escape(
-        "https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master"
-    ): r"https://results\.pre-commit\.ci/run/github/.*",
-}
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
 
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = 'sphinx'
 
-# Decides the language used for syntax highlighting of code blocks.
-highlight_language = "python3"
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "furo"
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the documentation.
+# further.  For a list of options available for each theme, see the
+# documentation.
 html_theme_options = {
-    "navigation_with_keys": True,
-    "dark_css_variables": {
-        "admonition-title-font-size": "0.95rem",
-        "admonition-font-size": "0.92rem",
-    },
-    "light_css_variables": {
-        "admonition-title-font-size": "0.95rem",
-        "admonition-font-size": "0.92rem",
-    },
-    "footer_icons": [
-        {
-            # Telegram channel logo
-            "name": "Telegram Channel",
-            "url": "https://t.me/pythontelegrambotchannel/",
-            # Following svg is from https://react-icons.github.io/react-icons/search?q=telegram
-            "html": (
-                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
-                'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
-                '<path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zM8.287 5.906c-.778.324-2.334.994'
-                "-4.666 2.01-.378.15-.577.298-.595.442-.03.243.275.339.69.47l.175.055c.408.133."
-                "958.288 1.243.294.26.006.549-.1.868-.32 2.179-1.471 3.304-2.214 3.374-2.23.0"
-                "5-.012.12-.026.166.016.047.041.042.12.037.141-.03.129-1.227 1.241-1.846 1.81"
-                "7-.193.18-.33.307-.358.336a8.154 8.154 0 0 1-.188.186c-.38.366-.664.64.015 1.08"
-                "8.327.216.589.393.85.571.284.194.568.387.936.629.093.06.183.125.27.187.331.23"
-                "6.63.448.997.414.214-.02.435-.22.547-.82.265-1.417.786-4.486.906-5.751a1.426 "
-                "1.426 0 0 0-.013-.315.337.337 0 0 0-.114-.217.526.526 0 0 0-.31-.093c-.3.005-.7"
-                '63.166-2.984 1.09z"></path></svg>'
-            ),
-            "class": "",
-        },
-        {  # Github logo
-            "name": "GitHub",
-            "url": "https://github.com/python-telegram-bot/python-telegram-bot/",
-            "html": (
-                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
-                'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 '
-                "2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.4"
-                "9-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23"
-                ".82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 "
-                "0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.2"
-                "7 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.5"
-                "1.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 "
-                '1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z">'
-                "</path></svg>"
-            ),
-            "class": "",
-        },
-        {  # PTB website logo - globe
-            "name": "python-telegram-bot website",
-            "url": "https://python-telegram-bot.org/",
-            "html": (
-                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
-                'viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">'
-                '<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8zm7.5-6.923c-.67.204-1.335.82-1.887 '
-                "1.855-.143.268-.276.56-.395.872.705.157 1.472.257 2.282.287V1.077zM4.249 3.53"
-                "9c.142-.384.304-.744.481-1.078a6.7 6.7 0 0 1 .597-.933A7.01 7.01 0 0 0 3.051 "
-                "3.05c.362.184.763.349 1.198.49zM3.509 7.5c.036-1.07.188-2.087.436-3.008a9.124 "
-                "9.124 0 0 1-1.565-.667A6.964 6.964 0 0 0 1.018 7.5h2.49zm1.4-2.741a12.344 "
-                "12.344 0 0 0-.4 2.741H7.5V5.091c-.91-.03-1.783-.145-2.591-.332zM8.5 5.09V7.5h"
-                "2.99a12.342 12.342 0 0 0-.399-2.741c-.808.187-1.681.301-2.591.332zM4.51 8.5c.03"
-                "5.987.176 1.914.399 2.741A13.612 13.612 0 0 1 7.5 10.91V8.5H4.51zm3.99 0v2.409"
-                "c.91.03 1.783.145 2.591.332.223-.827.364-1.754.4-2.741H8.5zm-3.282 3.696c.12.31"
-                "2.252.604.395.872.552 1.035 1.218 1.65 1.887 1.855V11.91c-.81.03-1.577.13-2.28"
-                "2.287zm.11 2.276a6.696 6.696 0 0 1-.598-.933 8.853 8.853 0 0 1-.481-1.079 8.38 "
-                "8.38 0 0 0-1.198.49 7.01 7.01 0 0 0 2.276 1.522zm-1.383-2.964A13.36 13.36 0 0 1"
-                " 3.508 8.5h-2.49a6.963 6.963 0 0 0 1.362 3.675c.47-.258.995-.482 1.565-.667zm"
-                "6.728 2.964a7.009 7.009 0 0 0 2.275-1.521 8.376 8.376 0 0 0-1.197-.49 8.853 "
-                "8.853 0 0 1-.481 1.078 6.688 6.688 0 0 1-.597.933zM8.5 11.909v3.014c.67-.204 "
-                "1.335-.82 1.887-1.855.143-.268.276-.56.395-.872A12.63 12.63 0 0 0 8.5 11.91zm"
-                "3.555-.401c.57.185 1.095.409 1.565.667A6.963 6.963 0 0 0 14.982 8.5h-2.49a1"
-                "3.36 13.36 0 0 1-.437 3.008zM14.982 7.5a6.963 6.963 0 0 0-1.362-3.675c-.47.25"
-                "8-.995.482-1.565.667.248.92.4 1.938.437 3.008h2.49zM11.27 2.461c.177.334.339.6"
-                "94.482 1.078a8.368 8.368 0 0 0 1.196-.49 7.01 7.01 0 0 0-2.275-1.52c.218.283.4"
-                "18.597.597.932zm-.488 1.343a7.765 7.765 0 0 0-.395-.872C9.835 1.897 9.17 1.282 "
-                '8.5 1.077V4.09c.81-.03 1.577-.13 2.282-.287z"></path></svg>'
-            ),
-            "class": "",
-        },
-    ],
+    'style_external_links': True,
 }
 
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = f"python-telegram-bot<br> v{version}"
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "ptb-logo_1024.png"
+html_logo = 'ptb-logo-orange.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "ptb-logo_1024.ico"
+html_favicon = 'ptb-logo-orange.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-html_css_files = [
-    "style_external_link.css",
-    "style_mermaid_diagrams.css",
-    "style_sidebar_brand.css",
-    "style_general.css",
-    "style_admonitions.css",
-    "style_images.css",
-]
+html_static_path = ['_static']
 
-html_permalinks_icon = "¶"  # Furo's default permalink icon is `#` which doesn't look great imo.
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "python-telegram-bot-doc"
-
-# The base URL which points to the root of the HTML documentation. It is used to indicate the
-# location of document using The Canonical Link Relation. Default: ''.
-# Set canonical URL from the Read the Docs Domain
-html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
-
-# Tell Jinja2 templates the build is running on Read the Docs
-html_context = {}
-if os.environ.get("READTHEDOCS", "") == "True":
-    html_context["READTHEDOCS"] = True
-
+htmlhelp_basename = 'python-telegram-bot-doc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    "papersize": "a4paper",
-    # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    "preamble": r"""\setcounter{tocdepth}{2}
+
+# The paper size ('letterpaper' or 'a4paper').
+    'papersize': 'a4paper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+    'preamble': r'''\setcounter{tocdepth}{2}
 \usepackage{enumitem}
-\setlistdepth{99}""",
-    # Latex figure (float) alignment
-    #'figure_align': 'htbp',
+\setlistdepth{99}''',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "python-telegram-bot.tex", "python-telegram-bot Documentation", author, "manual"),
+  (master_doc, 'python-telegram-bot.tex', u'python-telegram-bot Documentation',
+   author, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-latex_logo = "ptb-logo_1024.png"
+latex_logo = 'ptb-logo_1024.png'
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)]
+man_pages = [
+    (master_doc, 'python-telegram-bot', u'python-telegram-bot Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
 
-# rtd_sphinx_search_file_type = "un-minified"  # Configuration for furo-sphinx-search
 
 # -- Options for Texinfo output -------------------------------------------
 
@@ -321,36 +276,34 @@ man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentat
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (
-        master_doc,
-        "python-telegram-bot",
-        "python-telegram-bot Documentation",
-        author,
-        "python-telegram-bot",
-        "We have made you a wrapper you can't refuse",
-        "Miscellaneous",
-    ),
+  (master_doc, 'python-telegram-bot', u'python-telegram-bot Documentation',
+   author, 'python-telegram-bot', "We have made you a wrapper you can't refuse",
+   'Miscellaneous'),
 ]
 
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+# Napoleon stuff
+
+napoleon_use_admonition_for_examples = True
+
 # -- script stuff --------------------------------------------------------
 
-# Due to Sphinx behaviour, these imports only work when imported here, not at top of module.
 
-# Not used but must be imported for the linkcode extension to find it
-from docs.auxil.link_code import linkcode_resolve  # noqa: E402, F401
-from docs.auxil.sphinx_hooks import (  # noqa: E402
-    autodoc_process_bases,
-    autodoc_process_docstring,
-    autodoc_skip_member,
-)
-from docs.auxil.tg_const_role import CONSTANTS_ROLE, TGConstXRefRole  # noqa: E402
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    pass
 
 
-def setup(app: Sphinx):
-    app.connect("autodoc-skip-member", autodoc_skip_member)
-    app.connect("autodoc-process-bases", autodoc_process_bases)
-    # The default priority is 500. We want our function to run before napoleon doc-conversion
-    # and sphinx-paramlinks do, b/c otherwise the inserted kwargs in the bot methods won't show
-    # up in the objects.inv file that Sphinx generates (i.e. not in the search).
-    app.connect("autodoc-process-docstring", autodoc_process_docstring, priority=100)
-    app.add_role_to_domain("py", CONSTANTS_ROLE, TGConstXRefRole())
+def setup(app):
+    app.add_css_file("dark.css")
+    app.connect('autodoc-skip-member', autodoc_skip_member)

docs/source/contributing.rst

@@ -1 +0,0 @@
-.. include:: ../../.github/CONTRIBUTING.rst

docs/source/examples.arbitrarycallbackdatabot.rst

@@ -1,7 +0,0 @@
-``arbitrarycallbackdatabot.py``
-===============================
-
-.. literalinclude:: ../../examples/arbitrarycallbackdatabot.py
-   :language: python
-   :linenos:
-    

docs/source/examples.chatmemberbot.rst

@@ -1,7 +0,0 @@
-``chatmemberbot.py``
-====================
-
-.. literalinclude:: ../../examples/chatmemberbot.py
-   :language: python
-   :linenos:
-    

docs/source/examples.contexttypesbot.rst

@@ -1,7 +0,0 @@
-``contexttypesbot.py``
-======================
-
-.. literalinclude:: ../../examples/contexttypesbot.py
-   :language: python
-   :linenos:
-    

docs/source/examples.conversationbot.rst

@@ -1,13 +0,0 @@
-``conversationbot.py``
-======================
-
-.. literalinclude:: ../../examples/conversationbot.py
-   :language: python
-   :linenos:
-
-.. _conversationbot-diagram:
-
-State Diagram
--------------
-
-.. mermaid:: ../../examples/conversationbot.mmd

docs/source/examples.conversationbot2.rst

@@ -1,13 +0,0 @@
-``conversationbot2.py``
-=======================
-
-.. literalinclude:: ../../examples/conversationbot2.py
-   :language: python
-   :linenos:
-
-.. _conversationbot2-diagram:
-
-State Diagram
--------------
-
-.. mermaid:: ../../examples/conversationbot2.mmd

docs/source/examples.customwebhookbot.rst

@@ -1,43 +0,0 @@
-``customwebhookbot.py``
-=======================
-
-This example is available for different web frameworks.
-You can select your preferred framework by opening one of the tabs above the code example.
-
-.. hint::
-
-    The following examples show how different Python web frameworks can be used alongside PTB.
-    This can be useful for two use cases:
-
-    1. For extending the functionality of your existing bot to handling updates of external services
-    2. For extending the functionality of your exisiting web application to also include chat bot functionality
-
-    How the PTB and web framework components of the examples below are viewed surely depends on which use case one has in mind.
-    We are fully aware that a combination of PTB with web frameworks will always mean finding a tradeoff between usability and best practices for both PTB and the web framework and these examples are certainly far from optimal solutions.
-    Please understand them as starting points and use your expertise of the web framework of your choosing to build up on them.
-    You are of course also very welcome to help improve these examples!
-
-.. tab:: ``starlette``
-
-    .. literalinclude:: ../../examples/customwebhookbot/starlettebot.py
-       :language: python
-       :linenos:
-
-.. tab:: ``flask``
-
-    .. literalinclude:: ../../examples/customwebhookbot/flaskbot.py
-       :language: python
-       :linenos:
-
-.. tab:: ``quart``
-
-    .. literalinclude:: ../../examples/customwebhookbot/quartbot.py
-       :language: python
-       :linenos:
-
-.. tab:: ``Django``
-
-    .. literalinclude:: ../../examples/customwebhookbot/djangobot.py
-       :language: python
-       :linenos:
-    

docs/source/examples.deeplinking.rst

@@ -1,7 +0,0 @@
-``deeplinking.py``
-==================
-
-.. literalinclude:: ../../examples/deeplinking.py
-   :language: python
-   :linenos:
-    

docs/source/examples.echobot.rst

@@ -1,7 +0,0 @@
-``echobot.py``
-==============
-
-.. literalinclude:: ../../examples/echobot.py
-   :language: python
-   :linenos:
-