Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
Toggle table of contents sidebar

# CallbackDataCache

class telegram.ext.CallbackDataCache(bot, maxsize=1024, persistent_data=None)

  Bases: `object`

  A custom cache for storing the callback data of a `telegram.ext.ExtBot`. Internally, it keeps two mappings with fixed maximum size:

  - One for mapping the data received in callback queries to the cached objects

  - One for mapping the IDs of received callback queries to the cached objects

  The second mapping allows to manually drop data that has been cached for keyboards of messages sent via inline mode. If necessary, will drop the least recently used items.

  Important

  If you want to use this class, you must install PTB with the optional requirement `callback-data`, i.e.

      pip install "python-telegram-bot[callback-data]"

  Examples

  Arbitrary Callback Data Bot

  Available In

  `telegram.ext.ExtBot.callback_data_cache`

  See also

  Architecture Overview, Arbitrary callback_data

  New in version 13.6.

  Changed in version 20.0: To use this class, PTB must be installed via `pip install "python-telegram-bot[callback-data]"`.

  Parameters:

    - bot (`telegram.ext.ExtBot`) – The bot this cache is for.

    - maxsize (`int`, optional) – Maximum number of items in each of the internal mappings. Defaults to `1024`.

    - persistent_data (Tuple[List[Tuple[`str`, `float`, Dict[`str`, `object`]]], Dict[`str`, `str`]], optional) – Data to initialize the cache with, as returned by `telegram.ext.BasePersistence.get_callback_data()`.

  bot

    The bot this cache is for.

    Type:

      `telegram.ext.ExtBot`

  clear_callback_data(time_cutoff=None)

    Clears the stored callback data.

    Parameters:

      time_cutoff (`float` | `datetime.datetime`, optional) – Pass a UNIX timestamp or a `datetime.datetime` to clear only entries which are older. For timezone naive `datetime.datetime` objects, the default timezone of the bot will be used, which is UTC unless `telegram.ext.Defaults.tzinfo` is used.

  clear_callback_queries()

    Clears the stored callback query IDs.

  drop_data(callback_query)

    Deletes the data for the specified callback query.

    Note

    Will not raise exceptions in case the callback data is not found in the cache. Will raise `KeyError` in case the callback query can not be found in the cache.

    Parameters:

      callback_query (`telegram.CallbackQuery`) – The callback query.

    Raises:

      KeyError – If the callback query can not be found in the cache

  static extract_uuids(callback_data)

    Extracts the keyboard uuid and the button uuid from the given `callback_data`.

    Parameters:

      callback_data (`str`) – The `callback_data` as present in the button.

    Returns:

      Tuple of keyboard and button uuid

    Return type:

      (`str`, `str`)

  load_persistence_data(persistent_data)

    Loads data into the cache.

    Warning

    This method is not intended to be called by users directly.

    New in version 20.0.

    Parameters:

      persistent_data (Tuple[List[Tuple[`str`, `float`, Dict[`str`, `object`]]], Dict[`str`, `str`]], optional) – Data to load, as returned by `telegram.ext.BasePersistence.get_callback_data()`.

  property maxsize

    The maximum size of the cache.

    Changed in version 20.0: This property is now read-only.

    Type:

      `int`

  property persistence_data

    Tuple[List[Tuple[`str`, `float`, Dict[`str`, `object`]]], Dict[`str`, `str`]]: The data that needs to be persisted to allow caching callback data across bot reboots.

  process_callback_query(callback_query)

    Replaces the data in the callback query and the attached messages keyboard with the cached objects, if necessary. If the data could not be found, `telegram.ext.InvalidCallbackData` will be inserted. If `telegram.CallbackQuery.data` or `telegram.CallbackQuery.message` is present, this also saves the callback queries ID in order to be able to resolve it to the stored data.

    Note

    Also considers inserts data into the buttons of `telegram.Message.reply_to_message` and `telegram.Message.pinned_message` if necessary.

    Warning

    In place, i.e. the passed `telegram.CallbackQuery` will be changed!

    Parameters:

      callback_query (`telegram.CallbackQuery`) – The callback query.

  process_keyboard(reply_markup)

    Registers the reply markup to the cache. If any of the buttons have `callback_data`, stores that data and builds a new keyboard with the correspondingly replaced buttons. Otherwise, does nothing and returns the original reply markup.

    Parameters:

      reply_markup (`telegram.InlineKeyboardMarkup`) – The keyboard.

    Returns:

      The keyboard to be passed to Telegram.

    Return type:

      `telegram.InlineKeyboardMarkup`

  process_message(message)

    Replaces the data in the inline keyboard attached to the message with the cached objects, if necessary. If the data could not be found, `telegram.ext.InvalidCallbackData` will be inserted.

    Note

    Checks `telegram.Message.via_bot` and `telegram.Message.from_user` to check if the reply markup (if any) was actually sent by this cache’s bot. If it was not, the message will be returned unchanged.

    Note that this will fail for channel posts, as `telegram.Message.from_user` is `None` for those! In the corresponding reply markups the callback data will be replaced by `telegram.ext.InvalidCallbackData`.

    Warning

    - Does not consider `telegram.Message.reply_to_message` and `telegram.Message.pinned_message`. Pass them to this method separately.

    - In place, i.e. the passed `telegram.Message` will be changed!

    Parameters:

      message (`telegram.Message`) – The message.