TelegramObject¶
- 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. Thepickle
anddeepcopy()
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. Useset_bot()
andget_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 implementobject.__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 typetuple
.
- 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()
andto_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()
andto_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 thetelegram.Bot
instance set viaset_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()
- __delattr__(key)[source]¶
Overrides
object.__delattr__()
to prevent the deletion of attributes.- Raises:
- __eq__(other)[source]¶
Compares this object with
other
in terms of equality. If this object andother
are not objects of the same class, this comparison will fall back to Python’s default implementation ofobject.__eq__()
. Otherwise, both objects may be compared in terms of equality, if the corresponding subclass ofTelegramObject
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.
- __getitem__(item)[source]¶
Objects of this type are subscriptable with strings, where
telegram_object["attribute_name"]
is equivalent totelegram_object.attribute_name
.Tip
This is useful for dynamic attribute lookup, i.e.
telegram_object[arg]
where the value ofarg
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 keyfrom_user
. This is to account for special cases likeMessage.from_user
that deviate from the official Bot API.
- __getstate__()[source]¶
Overrides
object.__getstate__()
to customize the pickling process of objects of this type. The returned state does not contain thetelegram.Bot
instance set withset_bot()
(if any), as it can’t be pickled.
- __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:
- __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 valueNone
or are empty instances ofcollections.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:
- __setattr__(key, value)[source]¶
Overrides
object.__setattr__()
to prevent the overriding of attributes.- Raises:
- __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 fromapi_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
.
- classmethod de_json(data, bot=None)[source]¶
Converts JSON data to a Telegram object.
- Parameters:
bot (
telegram.Bot
, optional) –The bot associated with this object. Defaults to
None
, in which case shortcut methods will not be available.
- 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:
bot (
telegram.Bot
, optional) –The bot associated with these object. Defaults to
None
, in which case shortcut methods will not be available.
- Returns:
A tuple of Telegram objects.
- get_bot()[source]¶
Returns the
telegram.Bot
instance associated with this object.See also
- 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.See also
- 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.
- to_json()[source]¶
Gives a JSON representation of object.
Changed in version 20.0: Now includes all entries of
api_kwargs
.- Returns: