Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# TelegramObject

class telegram.TelegramObject(*, api_kwargs=None)

  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

    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)

    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)

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

    Raises:

      AttributeError –

  __eq__(other)

    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)

    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__()

    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__()

    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__()

    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)

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

    Raises:

      AttributeError –

  __setstate__(state)

    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)

    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)

    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()

    Returns the `telegram.Bot` instance associated with this object.

    See also

    `set_bot()`

    Raises:

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

  set_bot(bot)

    Sets the `telegram.Bot` instance associated with this object.

    See also

    `get_bot()`

    Parameters:

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

  to_dict(recursive=True)

    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()

    Gives a JSON representation of object.

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

    Returns:

      `str`