class telegram.TelegramObject(*, api_kwargs=None)[source]

Bases: object

Base class for most Telegram objects.

Objects of this type are subscriptable with strings. See __getitem__() for more details. The pickle and deepcopy() behavior of objects of this type are defined by __getstate__(), __setstate__() and __deepcopy__().

Tip

Objects of this type can be serialized via Python’s pickle module and pickled objects from one version of PTB are usually loadable in future versions. However, we can not guarantee that this compatibility will always be provided. At least a manual one-time conversion of the data may be needed on major updates of the library.

Changed in version 20.0:

  • Removed argument and attribute bot for several subclasses. Use set_bot() and get_bot() instead.

  • Removed the possibility to pass arbitrary keyword arguments for several subclasses.

  • String representations objects of this type was overhauled. See __repr__() for details. As this class doesn’t implement object.__str__(), the default implementation will be used, which is equivalent to __repr__().

  • Objects of this class (or subclasses) are now immutable. This means that you can’t set or delete attributes anymore. Moreover, attributes that were formerly of type list are now of type tuple.

Parameters:

api_kwargs (dict[str, any], optional) –

Arbitrary keyword arguments. Can be used to store data for which there are no dedicated attributes. These arguments are also considered by to_dict() and to_json(), i.e. when passing objects to Telegram. Passing them to Telegram is however not guaranteed to work for all kinds of objects, e.g. this will fail for objects that can not directly be JSON serialized.

Added in version 20.0.

api_kwargs[source]

Optional. Arbitrary keyword arguments. Used to store data for which there are no dedicated attributes. These arguments are also considered by to_dict() and to_json(), i.e. when passing objects to Telegram. Passing them to Telegram is however not guaranteed to work for all kinds of objects, e.g. this will fail for objects that can not directly be JSON serialized.

Added in version 20.0.

Type:

types.MappingProxyType [str, any]

__deepcopy__(memodict)[source]

Customizes how copy.deepcopy() processes objects of this type. The only difference to the default implementation is that the telegram.Bot instance set via set_bot() (if any) is not copied, but shared between the original and the copy, i.e.:

assert telegram_object.get_bot() is copy.deepcopy(telegram_object).get_bot()
Parameters:

memodict (dict) – A dictionary that maps objects to their copies.

Returns:

The copied object.

Return type:

telegram.TelegramObject

__delattr__(key)[source]

Overrides object.__delattr__() to prevent the deletion of attributes.

Raises:

AttributeError –

__eq__(other)[source]

Compares this object with other in terms of equality. If this object and other are not objects of the same class, this comparison will fall back to Python’s default implementation of object.__eq__(). Otherwise, both objects may be compared in terms of equality, if the corresponding subclass of TelegramObject has defined a set of attributes to compare and the objects are considered to be equal, if all of these attributes are equal. If the subclass has not defined a set of attributes to compare, a warning will be issued.

Tip

If instances of a class in the telegram module are comparable in terms of equality, the documentation of the class will state the attributes that will be used for this comparison.

Parameters:

other (object) – The object to compare with.

Returns:

bool

__getitem__(item)[source]

Objects of this type are subscriptable with strings, where telegram_object["attribute_name"] is equivalent to telegram_object.attribute_name.

Tip

This is useful for dynamic attribute lookup, i.e. telegram_object[arg] where the value of arg is determined at runtime. In all other cases, it’s recommended to use the dot notation instead, i.e. telegram_object.attribute_name.

Changed in version 20.0: telegram_object['from'] will look up the key from_user. This is to account for special cases like Message.from_user that deviate from the official Bot API.

Parameters:

item (str) – The name of the attribute to look up.

Returns:

object

Raises:

KeyError – If the object does not have an attribute with the appropriate name.

__getstate__()[source]

Overrides object.__getstate__() to customize the pickling process of objects of this type. The returned state does not contain the telegram.Bot instance set with set_bot() (if any), as it can’t be pickled.

Returns:

The state of the object.

Return type:

state (dict[str, object])

__hash__()[source]

Builds a hash value for this object such that the hash of two objects is equal if and only if the objects are equal in terms of __eq__().

Returns:

int

__repr__()[source]

Gives a string representation of this object in the form ClassName(attr_1=value_1, attr_2=value_2, ...), where attributes are omitted if they have the value None or are empty instances of collections.abc.Sized (e.g. list, dict, set, str, etc.).

As this class doesn’t implement object.__str__(), the default implementation will be used, which is equivalent to __repr__().

Returns:

str

__setattr__(key, value)[source]

Overrides object.__setattr__() to prevent the overriding of attributes.

Raises:

AttributeError –

__setstate__(state)[source]

Overrides object.__setstate__() to customize the unpickling process of objects of this type. Modifies the object in-place.

If any data was stored in the api_kwargs of the pickled object, this method checks if the class now has dedicated attributes for those keys and moves the values from api_kwargs to the dedicated attributes. This can happen, if serialized data is loaded with a new version of this library, where the new version was updated to account for updates of the Telegram Bot API.

If on the contrary an attribute was removed from the class, the value is not discarded but made available via api_kwargs.

Parameters:

state (dict) – The data to set as attributes of this object.

classmethod de_json(data, bot=None)[source]

Converts JSON data to a Telegram object.

Parameters:

  • data (dict[str, …]) – The JSON data.

  • bot (telegram.Bot, optional) –

    The bot associated with this object. Defaults to None, in which case shortcut methods will not be available.

    Changed in version 21.4: bot is now optional and defaults to None

Returns:

The Telegram object.

classmethod de_list(data, bot=None)[source]

Converts a list of JSON objects to a tuple of Telegram objects.

Changed in version 20.0:

  • Returns a tuple instead of a list.

  • Filters out any None values.

Parameters:

  • data (list[dict[str, …]]) – The JSON data.

  • bot (telegram.Bot, optional) –

    The bot associated with these object. Defaults to None, in which case shortcut methods will not be available.

    Changed in version 21.4: bot is now optional and defaults to None

Returns:

A tuple of Telegram objects.

get_bot()[source]

Returns the telegram.Bot instance associated with this object.

Raises:

RuntimeError – If no telegram.Bot instance was set for this object.

set_bot(bot)[source]

Sets the telegram.Bot instance associated with this object.

Parameters:

bot (telegram.Bot | None) – The bot instance.

to_dict(recursive=True)[source]

Gives representation of object as dict.

Changed in version 20.0:

  • Now includes all entries of api_kwargs.

  • Attributes whose values are empty sequences are no longer included.

Parameters:

recursive (bool, optional) –

If True, will convert any TelegramObjects (if found) in the attributes to a dictionary. Else, preserves it as an object itself. Defaults to True.

Added in version 20.0.

Returns:

dict

to_json()[source]

Gives a JSON representation of object.

Changed in version 20.0: Now includes all entries of api_kwargs.

Returns:

str