python-telegram-bot · Bibo-Joshi · Jun 6, 2021 · Mar 22, 2020 · Mar 23, 2020 · Mar 23, 2020
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -28,3 +28,4 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to
     - [ ] 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`
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -10,11 +10,11 @@ repos:
         - --diff
         - --check
 -   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.1
+    rev: 3.9.2
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v2.8.2
+    rev: v2.8.3
     hooks:
     -   id: pylint
         files: ^(telegram|examples)/.*\.py$
@@ -24,6 +24,7 @@ repos:
           - 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: v0.812
@@ -35,6 +36,7 @@ repos:
           - certifi
           - tornado>=6.1
           - APScheduler==3.6.3
+          - cachetools==4.2.2
           - . # this basically does `pip install -e .`
     -   id: mypy
         name: mypy-examples
@@ -46,9 +48,10 @@ repos:
           - certifi
           - tornado>=6.1
           - APScheduler==3.6.3
+          - cachetools==4.2.2
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.13.0
+    rev: v2.19.1
     hooks:
     -   id: pyupgrade
         files: ^(telegram|examples|tests)/.*\.py$

diff --git a/docs/source/telegram.ext.callbackdatacache.rst b/docs/source/telegram.ext.callbackdatacache.rst
@@ -0,0 +1,8 @@
+:github_url: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/telegram/ext/callbackdatacache.py
+
+telegram.ext.CallbackDataCache
+==============================
+
+.. autoclass:: telegram.ext.CallbackDataCache
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.ext.extbot.rst b/docs/source/telegram.ext.extbot.rst
@@ -0,0 +1,7 @@
+:github_url: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/telegram/ext/extbot.py
+
+telegram.ext.ExtBot
+===================
+
+.. autoclass:: telegram.ext.ExtBot
+    :show-inheritance:
diff --git a/docs/source/telegram.ext.invalidcallbackdata.rst b/docs/source/telegram.ext.invalidcallbackdata.rst
@@ -0,0 +1,8 @@
+:github_url: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/telegram/ext/callbackdatacache.py
+
+telegram.ext.InvalidCallbackData
+================================
+
+.. autoclass:: telegram.ext.InvalidCallbackData
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst
@@ -3,6 +3,7 @@ telegram.ext package
 
 .. toctree::
 
+    telegram.ext.extbot
     telegram.ext.updater
     telegram.ext.dispatcher
     telegram.ext.dispatcherhandlerstop
@@ -47,6 +48,14 @@ Persistence
     telegram.ext.picklepersistence
     telegram.ext.dictpersistence
 
+Arbitrary Callback Data
+-----------------------
+
+.. toctree::
+
+    telegram.ext.callbackdatacache
+    telegram.ext.invalidcallbackdata
+
 utils
 -----
 

diff --git a/examples/README.md b/examples/README.md
@@ -52,5 +52,8 @@ A basic example on how `(my_)chat_member` updates can be used.
 ### [`contexttypesbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/contexttypesbot.py)
 This example showcases how `telegram.ext.ContextTypes` can be used to customize the `context` argument of handler and job callbacks.
 
+### [`arbitrarycallbackdatabot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/arbitrarycallbackdatabot.py)
+This example showcases how PTBs "arbitrary callback data" feature can be used.
+
 ## Pure API
 The [`rawapibot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/rawapibot.py) example uses only the pure, "bare-metal" API wrapper.
diff --git a/examples/arbitrarycallbackdatabot.py b/examples/arbitrarycallbackdatabot.py
@@ -0,0 +1,110 @@
+#!/usr/bin/env python
+# pylint: disable=C0116,W0613
+# This program is dedicated to the public domain under the CC0 license.
+
+"""This example showcases how PTBs "arbitrary callback data" feature can be used.
+
+For detailed info on arbitrary callback data, see the wiki page at https://git.io/JGBDI
+"""
+import logging
+from typing import List, Tuple, cast
+
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    CallbackQueryHandler,
+    CallbackContext,
+    InvalidCallbackData,
+    PicklePersistence,
+)
+
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
+logger = logging.getLogger(__name__)
+
+
+def start(update: Update, context: CallbackContext) -> None:
+    """Sends a message with 5 inline buttons attached."""
+    number_list: List[int] = []
+    update.message.reply_text('Please choose:', reply_markup=build_keyboard(number_list))
+
+
+def help_command(update: Update, context: CallbackContext) -> None:
+    """Displays info on how to use the bot."""
+    update.message.reply_text(
+        "Use /start to test this bot. Use /clear to clear the stored data so that you can see "
+        "what happens, if the button data is not available. "
+    )
+
+
+def clear(update: Update, context: CallbackContext) -> None:
+    """Clears the callback data cache"""
+    context.bot.callback_data_cache.clear_callback_data()  # type: ignore[attr-defined]
+    context.bot.callback_data_cache.clear_callback_queries()  # type: ignore[attr-defined]
+    update.effective_message.reply_text('All clear!')
+
+
+def build_keyboard(current_list: List[int]) -> InlineKeyboardMarkup:
+    """Helper function to build the next inline keyboard."""
+    return InlineKeyboardMarkup.from_column(
+        [InlineKeyboardButton(str(i), callback_data=(i, current_list)) for i in range(1, 6)]
+    )
+
+
+def list_button(update: Update, context: CallbackContext) -> None:
+    """Parses the CallbackQuery and updates the message text."""
+    query = update.callback_query
+    query.answer()
+    # Get the data from the callback_data.
+    # If you're using a type checker like MyPy, you'll have to use typing.cast
+    # to make the checker get the expected type of the callback_data
+    number, number_list = cast(Tuple[int, List[int]], query.data)
+    # append the number to the list
+    number_list.append(number)
+
+    query.edit_message_text(
+        text=f"So far you've selected {number_list}. Choose the next item:",
+        reply_markup=build_keyboard(number_list),
+    )
+
+    # we can delete the data stored for the query, because we've replaced the buttons
+    context.drop_callback_data(query)
+
+
+def handle_invalid_button(update: Update, context: CallbackContext) -> None:
+    """Informs the user that the button is no longer available."""
+    update.callback_query.answer()
+    update.effective_message.edit_text(
+        'Sorry, I could not process this button click 😕 Please send /start to get a new keyboard.'
+    )
+
+
+def main() -> None:
+    """Run the bot."""
+    # We use persistence to demonstrate how buttons can still work after the bot was restarted
+    persistence = PicklePersistence(
+        filename='arbitrarycallbackdatabot.pickle', store_callback_data=True
+    )
+    # Create the Updater and pass it your bot's token.
+    updater = Updater("TOKEN", persistence=persistence, arbitrary_callback_data=True)
+
+    updater.dispatcher.add_handler(CommandHandler('start', start))
+    updater.dispatcher.add_handler(CommandHandler('help', help_command))
+    updater.dispatcher.add_handler(CommandHandler('clear', clear))
+    updater.dispatcher.add_handler(
+        CallbackQueryHandler(handle_invalid_button, pattern=InvalidCallbackData)
+    )
+    updater.dispatcher.add_handler(CallbackQueryHandler(list_button))
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until the user presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -4,12 +4,12 @@ cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3
 pre-commit
 # Make sure that the versions specified here match the pre-commit settings!
 black==20.8b1
-flake8==3.9.1
-pylint==2.8.2
+flake8==3.9.2
+pylint==2.8.3
 mypy==0.812
-pyupgrade==2.13.0
+pyupgrade==2.19.1
 
-pytest==6.2.3
+pytest==6.2.4
 
 flaky
 beautifulsoup4

diff --git a/requirements.txt b/requirements.txt
@@ -5,3 +5,4 @@ certifi
 tornado>=6.1
 APScheduler==3.6.3
 pytz>=2018.6
+cachetools==4.2.2