telegram.ext.BasePersistence

class telegram.ext.BasePersistence(*args, **kwargs)

Bases: Generic[telegram.ext.utils.types.UD, telegram.ext.utils.types.CD, telegram.ext.utils.types.BD], abc.ABC

Interface class for adding persistence to your bot. Subclass this object for different implementations of a persistent bot.

All relevant methods must be overwritten. This includes:

If you don’t actually need one of those methods, a simple pass is enough. For example, if store_bot_data=False, you don’t need get_bot_data(), update_bot_data() or refresh_bot_data().

Warning

Persistence will try to replace telegram.Bot instances by REPLACED_BOT and insert the bot set with set_bot() upon loading of the data. This is to ensure that changes to the bot apply to the saved objects, too. If you change the bots token, this may lead to e.g. Chat not found errors. For the limitations on replacing bots see replace_bot() and insert_bot().

Note

replace_bot() and insert_bot() are used independently of the implementation of the update/get_*() methods, i.e. you don’t need to worry about it while implementing a custom persistence subclass.

Parameters

  • store_user_data (bool, optional) – Whether user_data should be saved by this persistence class. Default is True.

  • store_chat_data (bool, optional) – Whether chat_data should be saved by this persistence class. Default is True .

  • store_bot_data (bool, optional) – Whether bot_data should be saved by this persistence class. Default is True.

  • store_callback_data (bool, optional) –

    Whether callback_data should be saved by this persistence class. Default is False.

    New in version 13.6.

store_user_data

Optional, Whether user_data should be saved by this persistence class.

Type

bool

store_chat_data

Optional. Whether chat_data should be saved by this persistence class.

Type

bool

store_bot_data

Optional. Whether bot_data should be saved by this persistence class.

Type

bool

store_callback_data

Optional. Whether callback_data should be saved by this persistence class.

New in version 13.6.

Type

bool

REPLACED_BOT: ClassVar[str] = 'bot_instance_replaced_by_ptb_persistence'

Placeholder for telegram.Bot instances replaced in saved data.

Type

str

flush()

Will be called by telegram.ext.Updater upon receiving a stop signal. Gives the persistence a chance to finish up saving or close a database connection gracefully.

abstract get_bot_data()

Will be called by telegram.ext.Dispatcher upon creation with a persistence object. It should return the bot_data if stored, or an empty telegram.ext.utils.types.BD.

Returns

The restored bot data.

Return type

telegram.ext.utils.types.BD

get_callback_data()

Will be called by telegram.ext.Dispatcher upon creation with a persistence object. If callback data was stored, it should be returned.

New in version 13.6.

Returns

The restored meta data or None, if no data was stored.

Return type

Optional[telegram.ext.utils.types.CDCData]

abstract get_chat_data()

Will be called by telegram.ext.Dispatcher upon creation with a persistence object. It should return the chat_data if stored, or an empty defaultdict(telegram.ext.utils.types.CD) with integer keys.

Returns

The restored chat data.

Return type

DefaultDict[int, telegram.ext.utils.types.CD]

abstract get_conversations(name)

Will be called by telegram.ext.Dispatcher when a telegram.ext.ConversationHandler is added if telegram.ext.ConversationHandler.persistent is True. It should return the conversations for the handler with name or an empty dict

Parameters

name (str) – The handlers name.

Returns

The restored conversations for the handler.

Return type

dict

abstract get_user_data()

Will be called by telegram.ext.Dispatcher upon creation with a persistence object. It should return the user_data if stored, or an empty defaultdict(telegram.ext.utils.types.UD) with integer keys.

Returns

The restored user data.

Return type

DefaultDict[int, telegram.ext.utils.types.UD]

insert_bot(obj)

Replaces all instances of REPLACED_BOT that occur within the passed object with bot. Currently, this handles objects of type list, tuple, set, frozenset, dict, defaultdict and objects that have a __dict__ or __slots__ attribute, excluding classes and objects that can’t be copied with copy.copy. If the parsing of an object fails, the object will be returned unchanged and the error will be logged.

Parameters

obj (object) – The object

Returns

Copy of the object with Bot instances inserted.

Return type

obj

refresh_bot_data(bot_data)

Will be called by the telegram.ext.Dispatcher before passing the bot_data to a callback. Can be used to update data stored in bot_data from an external source.

New in version 13.6.

Parameters

bot_data (telegram.ext.utils.types.BD) – The bot_data.

refresh_chat_data(chat_id, chat_data)

Will be called by the telegram.ext.Dispatcher before passing the chat_data to a callback. Can be used to update data stored in chat_data from an external source.

New in version 13.6.

Parameters

  • chat_id (int) – The chat ID this chat_data is associated with.

  • chat_data (telegram.ext.utils.types.CD) – The chat_data of a single chat.

refresh_user_data(user_id, user_data)

Will be called by the telegram.ext.Dispatcher before passing the user_data to a callback. Can be used to update data stored in user_data from an external source.

New in version 13.6.

Parameters

  • user_id (int) – The user ID this user_data is associated with.

  • user_data (telegram.ext.utils.types.UD) – The user_data of a single user.

classmethod replace_bot(obj)

Replaces all instances of telegram.Bot that occur within the passed object with REPLACED_BOT. Currently, this handles objects of type list, tuple, set, frozenset, dict, defaultdict and objects that have a __dict__ or __slots__ attribute, excluding classes and objects that can’t be copied with copy.copy. If the parsing of an object fails, the object will be returned unchanged and the error will be logged.

Parameters

obj (object) – The object

Returns

Copy of the object with Bot instances replaced.

Return type

obj

set_bot(bot)

Set the Bot to be used by this persistence instance.

Parameters

bot (telegram.Bot) – The bot.

abstract update_bot_data(data)

Will be called by the telegram.ext.Dispatcher after a handler has handled an update.

Parameters

data (telegram.ext.utils.types.BD) – The telegram.ext.Dispatcher.bot_data.

update_callback_data(data)

Will be called by the telegram.ext.Dispatcher after a handler has handled an update.

New in version 13.6.

Parameters

data (telegram.ext.utils.types.CDCData) – The relevant data to restore telegram.ext.CallbackDataCache.

abstract update_chat_data(chat_id, data)

Will be called by the telegram.ext.Dispatcher after a handler has handled an update.

Parameters
abstract update_conversation(name, key, new_state)

Will be called when a telegram.ext.ConversationHandler changes states. This allows the storage of the new state in the persistence.

Parameters

  • name (str) – The handler’s name.

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

  • new_state (tuple | any) – The new state for the given key.

abstract update_user_data(user_id, data)

Will be called by the telegram.ext.Dispatcher after a handler has handled an update.

Parameters