Skip to content
Back to top
View this page

# PicklePersistence

class telegram.ext.PicklePersistence(filepath, store_data=None, single_file=True, on_flush=False, update_interval=60, context_types=None)

  Bases: `telegram.ext.BasePersistence`

  Using python’s builtin `pickle` for making your bot persistent.

  Attention

  The interface provided by this class is intended to be accessed exclusively by `Application`. Calling any of the methods below manually might interfere with the integration of persistence into `Application`.

  Note

  This implementation of `BasePersistence` uses the functionality of the pickle module to support serialization of bot instances. Specifically any reference to `bot` will be replaced by a placeholder before pickling and `bot` will be inserted back when loading the data.

  Examples

  Persistent Conversation Bot

  See also

  Making Your Bot Persistent

  Use In

  `telegram.ext.ApplicationBuilder.persistence()`

  Available In

  `telegram.ext.Application.persistence`

  Changed in version 20.0:

  - The parameters and attributes `store_*_data` were replaced by `store_data`.

  - The parameter and attribute `filename` were replaced by `filepath`.

  - `filepath` now also accepts `pathlib.Path` as argument.

  Parameters:

    - filepath (`str` | `pathlib.Path`) – The filepath for storing the pickle files. When `single_file` is `False` this will be used as a prefix.

    - store_data (`PersistenceInput`, optional) – Specifies which kinds of data will be saved by this persistence instance. By default, all available kinds of data will be saved.

    - single_file (`bool`, optional) – When `False` will store 5 separate files of filename_user_data, filename_bot_data, filename_chat_data, filename_callback_data and filename_conversations. Default is `True`.

    - on_flush (`bool`, optional) – When `True` will only save to file when `flush()` is called and keep data in memory until that happens. When `False` will store data on any transaction and on call to `flush()`. Default is `False`.

    - context_types (`telegram.ext.ContextTypes`, optional) –

      Pass an instance of `telegram.ext.ContextTypes` to customize the types used in the `context` interface. If not passed, the defaults documented in `telegram.ext.ContextTypes` will be used.

      Added in version 13.6.

    - update_interval (`int` | `float`, optional) –

      The `Application` will update the persistence in regular intervals. This parameter specifies the time (in seconds) to wait between two consecutive runs of updating the persistence. Defaults to 60 seconds.

      Added in version 20.0.

  filepath

    The filepath for storing the pickle files. When `single_file` is `False` this will be used as a prefix.

    Type:

      `str` | `pathlib.Path`

  store_data

    Specifies which kinds of data will be saved by this persistence instance.

    Type:

      `PersistenceInput`

  single_file

    Optional. When `False` will store 5 separate files of filename_user_data, filename_bot_data, filename_chat_data, filename_callback_data and filename_conversations. Default is `True`.

    Type:

      `bool`

  on_flush

    Optional. When `True` will only save to file when `flush()` is called and keep data in memory until that happens. When `False` will store data on any transaction and on call to `flush()`. Default is `False`.

    Type:

      `bool`

  context_types

    Container for the types used in the `context` interface.

    Added in version 13.6.

    Type:

      `telegram.ext.ContextTypes`

  async drop_chat_data(chat_id)

    Will delete the specified key from the `chat_data` and depending on `on_flush` save the pickle file.

    Added in version 20.0.

    Parameters:

      chat_id (`int`) – The chat id to delete from the persistence.

  async drop_user_data(user_id)

    Will delete the specified key from the `user_data` and depending on `on_flush` save the pickle file.

    Added in version 20.0.

    Parameters:

      user_id (`int`) – The user id to delete from the persistence.

  async flush()

    Will save all data in memory to pickle file(s).

  async get_bot_data()

    Returns the bot_data from the pickle file if it exists or an empty object of type `dict` | `telegram.ext.ContextTypes.bot_data`.

    Returns:

      The restored bot data.

    Return type:

      `dict` | `telegram.ext.ContextTypes.bot_data`

  async get_callback_data()

    Returns the callback data from the pickle file if it exists or `None`.

    Added in version 13.6.

    Returns:

      tuple[list[tuple[`str`, `float`, dict[`str`, `object`]]], dict[`str`, `str`]] | `None`: The restored metadata or `None`, if no data was stored.

  async get_chat_data()

    Returns the chat_data from the pickle file if it exists or an empty `dict`.

    Returns:

      The restored chat data.

    Return type:

      dict[`int`, `dict`]

  async get_conversations(name)

    Returns the conversations from the pickle file if it exists or an empty dict.

    Parameters:

      name (`str`) – The handlers name.

    Returns:

      The restored conversations for the handler.

    Return type:

      `dict`

  async get_user_data()

    Returns the user_data from the pickle file if it exists or an empty `dict`.

    Returns:

      The restored user data.

    Return type:

      dict[`int`, `dict`]

  async refresh_bot_data(bot_data)

    Does nothing.

    Added in version 13.6.

    See also

    `telegram.ext.BasePersistence.refresh_bot_data()`

  async refresh_chat_data(chat_id, chat_data)

    Does nothing.

    Added in version 13.6.

    See also

    `telegram.ext.BasePersistence.refresh_chat_data()`

  async refresh_user_data(user_id, user_data)

    Does nothing.

    Added in version 13.6.

    See also

    `telegram.ext.BasePersistence.refresh_user_data()`

  async update_bot_data(data)

    Will update the bot_data and depending on `on_flush` save the pickle file.

    Parameters:

      data (`dict` | `telegram.ext.ContextTypes.bot_data`) – The `telegram.ext.Application.bot_data`.

  async update_callback_data(data)

    Will update the callback_data (if changed) and depending on `on_flush` save the pickle file.

    Added in version 13.6.

    Parameters:

      data (tuple[list[tuple[`str`, `float`, dict[`str`, `object`]]], dict[`str`, `str`]]) – The relevant data to restore `telegram.ext.CallbackDataCache`.

  async update_chat_data(chat_id, data)

    Will update the chat_data and depending on `on_flush` save the pickle file.

    Parameters:

      - chat_id (`int`) – The chat the data might have been changed for.

      - data (`dict`) – The `telegram.ext.Application.chat_data` `[chat_id]`.

  async update_conversation(name, key, new_state)

    Will update the conversations for the given handler and depending on `on_flush` save the pickle file.

    Parameters:

      - name (`str`) – The handler’s name.

      - key (`tuple`) – The key the state is changed for.

      - new_state (`object`) – The new state for the given key.

  async update_user_data(user_id, data)

    Will update the user_data and depending on `on_flush` save the pickle file.

    Parameters:

      - user_id (`int`) – The user the data might have been changed for.

      - data (`dict`) – The `telegram.ext.Application.user_data` `[user_id]`.