"""Base class for most Telegram objects.

__slots__ = ("_bot", "_frozen", "_id_attrs", "api_kwargs")

# Used to cache the names of the parameters of the __init__ method of the class

# Must be a private attribute to avoid name clashes between subclasses

__INIT_PARAMS: ClassVar[set[str]] = set()

# Used to check if __INIT_PARAMS has been set for the current class. Unfortunately, we can't

# just check if `__INIT_PARAMS is None`, since subclasses use the parent class' __INIT_PARAMS

# unless it's overridden

__INIT_PARAMS_CHECK: Optional[type["TelegramObject"]] = None

def __init__(self, *, api_kwargs: Optional[JSONDict] = None) -> None:

# Setting _frozen to `False` here means that classes without arguments still need to

# implement __init__. However, with `True` would mean increased usage of

# `with self._unfrozen()` in the `__init__` of subclasses and we have fewer empty

# classes than classes with arguments.

self._frozen: bool = False

self._id_attrs: tuple[object, ...] = ()

self._bot: Optional[Bot] = None

# We don't do anything with api_kwargs here - see docstring of _apply_api_kwargs

self.api_kwargs: Mapping[str, Any] = MappingProxyType(api_kwargs or {})

def __eq__(self, other: object) -> bool:

"""Compares this object with :paramref:`other` in terms of equality.

if isinstance(other, self.__class__):

if not self._id_attrs:

warn(

f"Objects of type {self.__class__.__name__} can not be meaningfully tested for"

" equivalence.",

stacklevel=2,

)

if not other._id_attrs:

warn(

f"Objects of type {other.__class__.__name__} can not be meaningfully tested"

" for equivalence.",

stacklevel=2,

)

return self._id_attrs == other._id_attrs

return super().__eq__(other)

def __hash__(self) -> int:

"""Builds a hash value for this object such that the hash of two objects is equal if and

if self._id_attrs:

return hash((self.__class__, self._id_attrs))

return super().__hash__()

def __setattr__(self, key: str, value: object) -> None:

"""Overrides :meth:`object.__setattr__` to prevent the overriding of attributes.

# protected attributes can always be set for convenient internal use

if key[0] == "_" or not getattr(self, "_frozen", True):

super().__setattr__(key, value)

return

raise AttributeError(

f"Attribute `{key}` of class `{self.__class__.__name__}` can't be set!"

)

def __delattr__(self, key: str) -> None:

"""Overrides :meth:`object.__delattr__` to prevent the deletion of attributes.

# protected attributes can always be set for convenient internal use

if key[0] == "_" or not getattr(self, "_frozen", True):

super().__delattr__(key)

return

raise AttributeError(

f"Attribute `{key}` of class `{self.__class__.__name__}` can't be deleted!"

)

def __repr__(self) -> str:

"""Gives a string representation of this object in the form

# * `__repr__` goal is to be unambiguous

# * `__str__` goal is to be readable

# * `str()` calls `__repr__`, if `__str__` is not defined

# In our case "unambiguous" and "readable" largely coincide, so we can use the same logic.

as_dict = self._get_attrs(recursive=False, include_private=False)

if not self.api_kwargs:

# Drop api_kwargs from the representation, if empty

as_dict.pop("api_kwargs", None)

else:

# Otherwise, we want to skip the "mappingproxy" part of the repr

as_dict["api_kwargs"] = dict(self.api_kwargs)

contents = ", ".join(

f"{k}={as_dict[k]!r}"

for k in sorted(as_dict.keys())

if (

as_dict[k] is not None

and not (

isinstance(as_dict[k], Sized)

and len(as_dict[k]) == 0 # type: ignore[arg-type]

)

)

)

return f"{self.__class__.__name__}({contents})"

def __getitem__(self, item: str) -> object:

"""

if item == "from":

item = "from_user"

try:

return getattr(self, item)

except AttributeError as exc:

raise KeyError(

f"Objects of type {self.__class__.__name__} don't have an attribute called "

f"`{item}`."

) from exc

def __getstate__(self) -> dict[str, Union[str, object]]:

"""

out = self._get_attrs(

include_private=True, recursive=False, remove_bot=True, convert_default_vault=False

)

# MappingProxyType is not pickable, so we convert it to a dict and revert in

# __setstate__

out["api_kwargs"] = dict(self.api_kwargs)

return out

def __setstate__(self, state: dict[str, object]) -> None:

"""

self._unfreeze()

# Make sure that we have a `_bot` attribute. This is necessary, since __getstate__ omits

# this as Bots are not pickable.

self._bot = None

# get api_kwargs first because we may need to add entries to it (see try-except below)

api_kwargs = cast(dict[str, object], state.pop("api_kwargs", {}))

# get _frozen before the loop to avoid setting it to True in the loop

frozen = state.pop("_frozen", False)

for key, val in state.items():

try:

setattr(self, key, val)

except AttributeError:

# So an attribute was deprecated and removed from the class. Let's handle this:

# 1) Is the attribute now a property with no setter? Let's check that:

if isinstance(getattr(self.__class__, key, None), property):

# It is, so let's try to set the "private attribute" instead

try:

setattr(self, f"_{key}", val)

# If this fails as well, guess we've completely removed it. Let's add it to

# api_kwargs as fallback

except AttributeError:

api_kwargs[key] = val

# 2) The attribute is a private attribute, i.e. it went through case 1) in the past

elif key.startswith("_"):

continue # skip adding this to api_kwargs, the attribute is lost forever.

api_kwargs[key] = val # add it to api_kwargs as fallback

# For api_kwargs we first apply any kwargs that are already attributes of the object

# and then set the rest as MappingProxyType attribute. Converting to MappingProxyType

# is necessary, since __getstate__ converts it to a dict as MPT is not pickable.

self._apply_api_kwargs(api_kwargs)

self.api_kwargs = MappingProxyType(api_kwargs)

# Apply freezing if necessary

# we .get(…) the setting for backwards compatibility with objects that were pickled

# before the freeze feature was introduced

if frozen:

self._freeze()

def __deepcopy__(self: Tele_co, memodict: dict[int, object]) -> Tele_co:

"""

bot = self._bot # Save bot so we can set it after copying

self.set_bot(None) # set to None so it is not deepcopied

cls = self.__class__

result = cls.__new__(cls) # create a new instance

memodict[id(self)] = result # save the id of the object in the dict

result._frozen = False # unfreeze the new object for setting the attributes

# now we set the attributes in the deepcopied object

for k in self._get_attrs_names(include_private=True):

if k == "_frozen":

# Setting the frozen status to True would prevent the attributes from being set

continue

if k == "api_kwargs":

# Need to copy api_kwargs manually, since it's a MappingProxyType is not

# pickable and deepcopy uses the pickle interface

setattr(result, k, MappingProxyType(deepcopy(dict(self.api_kwargs), memodict)))

continue

try:

setattr(result, k, deepcopy(getattr(self, k), memodict))

except AttributeError:

# Skip missing attributes. This can happen if the object was loaded from a pickle

# file that was created with an older version of the library, where the class

# did not have the attribute yet.

continue

# Apply freezing if necessary

if self._frozen:

result._freeze()

result.set_bot(bot) # Assign the bots back

self.set_bot(bot)

return result

@staticmethod

def _parse_data(data: Optional[JSONDict]) -> Optional[JSONDict]:

"""Should be called by subclasses that override de_json to ensure that the input

return None if data is None else data.copy()

@classmethod

def _de_json(

cls: type[Tele_co],

data: Optional[JSONDict],

bot: Optional["Bot"],

api_kwargs: Optional[JSONDict] = None,

) -> Optional[Tele_co]:

if data is None:

return None

# try-except is significantly faster in case we already have a correct argument set

try:

obj = cls(**data, api_kwargs=api_kwargs)

except TypeError as exc:

if "__init__() got an unexpected keyword argument" not in str(exc):

raise

if cls.__INIT_PARAMS_CHECK is not cls:

signature = inspect.signature(cls)

cls.__INIT_PARAMS = set(signature.parameters.keys())

cls.__INIT_PARAMS_CHECK = cls

api_kwargs = api_kwargs or {}

existing_kwargs: JSONDict = {}

for key, value in data.items():

(existing_kwargs if key in cls.__INIT_PARAMS else api_kwargs)[key] = value

obj = cls(api_kwargs=api_kwargs, **existing_kwargs)

obj.set_bot(bot=bot)

return obj

@classmethod

def de_json(

cls: type[Tele_co], data: Optional[JSONDict], bot: Optional["Bot"] = None

) -> Optional[Tele_co]:

"""Converts JSON data to a Telegram object.

return cls._de_json(data=data, bot=bot)

@classmethod

def de_list(

cls: type[Tele_co], data: Optional[list[JSONDict]], bot: Optional["Bot"] = None

) -> tuple[Tele_co, ...]:

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

if not data:

return ()

return tuple(obj for obj in (cls.de_json(d, bot) for d in data) if obj is not None)

@contextmanager

def _unfrozen(self: Tele_co) -> Iterator[Tele_co]:

"""Context manager to temporarily unfreeze the object. For internal use only.

self._unfreeze()

yield self

self._freeze()

def _freeze(self) -> None:

self._frozen = True

def _unfreeze(self) -> None:

self._frozen = False

def _apply_api_kwargs(self, api_kwargs: JSONDict) -> None:

"""Loops through the api kwargs and for every key that exists as attribute of the

# we convert to list to ensure that the list doesn't change length while we loop

for key in list(api_kwargs.keys()):

# property attributes are not settable, so we need to set the private attribute

if isinstance(getattr(self.__class__, key, None), property):

# if setattr fails, we'll just leave the value in api_kwargs:

with contextlib.suppress(AttributeError):

setattr(self, f"_{key}", api_kwargs.pop(key))

elif getattr(self, key, True) is None:

setattr(self, key, api_kwargs.pop(key))

def _get_attrs_names(self, include_private: bool) -> Iterator[str]:

"""

# We want to get all attributes for the class, using self.__slots__ only includes the

# attributes used by that class itself, and not its superclass(es). Hence, we get its MRO

# and then get their attributes. The `[:-1]` slice excludes the `object` class

all_slots = (s for c in self.__class__.__mro__[:-1] for s in c.__slots__) # type: ignore

# chain the class's slots with the user defined subclass __dict__ (class has no slots)

all_attrs = (

chain(all_slots, self.__dict__.keys()) if hasattr(self, "__dict__") else all_slots

)

if include_private:

return all_attrs

return (attr for attr in all_attrs if not attr.startswith("_"))

def _get_attrs(

self,

include_private: bool = False,

recursive: bool = False,

remove_bot: bool = False,

convert_default_vault: bool = True,

) -> dict[str, Union[str, object]]:

"""This method is used for obtaining the attributes of the object.

data = {}

for key in self._get_attrs_names(include_private=include_private):

value = (

DefaultValue.get_value(getattr(self, key, None))

if convert_default_vault

else getattr(self, key, None)

)

if value is not None:

if recursive and hasattr(value, "to_dict"):

data[key] = value.to_dict(recursive=True)

else:

data[key] = value

elif not recursive:

data[key] = value

if recursive and data.get("from_user"):

data["from"] = data.pop("from_user", None)

if remove_bot:

data.pop("_bot", None)

return data

def to_json(self) -> str:

"""Gives a JSON representation of object.

return json.dumps(self.to_dict())

def to_dict(self, recursive: bool = True) -> JSONDict:

"""Gives representation of object as :obj:`dict`.

out = self._get_attrs(recursive=recursive)

# Now we should convert TGObjects to dicts inside objects such as sequences, and convert

# datetimes to timestamps. This mostly eliminates the need for subclasses to override

# `to_dict`

pop_keys: set[str] = set()

for key, value in out.items():

if isinstance(value, (tuple, list)):

if not value:

# not popping directly to avoid changing the dict size during iteration

pop_keys.add(key)

continue

val = [] # empty list to append our converted values to

for item in value:

if hasattr(item, "to_dict"):

val.append(item.to_dict(recursive=recursive))

# This branch is useful for e.g. tuple[tuple[PhotoSize|KeyboardButton]]

elif isinstance(item, (tuple, list)):

val.append(

[

i.to_dict(recursive=recursive) if hasattr(i, "to_dict") else i

for i in item

]

)

else: # if it's not a TGObject, just append it. E.g. [TGObject, 2]

val.append(item)

out[key] = val

elif isinstance(value, datetime.datetime):

out[key] = to_timestamp(value)

elif isinstance(value, datetime.timedelta):

out[key] = value.total_seconds()

for key in pop_keys:

out.pop(key)

# Effectively "unpack" api_kwargs into `out`:

out.update(out.pop("api_kwargs", {})) # type: ignore[call-overload]

return out

def get_bot(self) -> "Bot":

"""Returns the :class:`telegram.Bot` instance associated with this object.

if self._bot is None:

raise RuntimeError(

"This object has no bot associated with it. Shortcuts cannot be used."

)

return self._bot

def set_bot(self, bot: Optional["Bot"]) -> None:

"""Sets the :class:`telegram.Bot` instance associated with this object.