1#!/usr/bin/env python 2# pylint: disable=C0103,W0622 3# 4# A library that provides a Python interface to the Telegram Bot API 5# Copyright (C) 2015-2020 6# Leandro Toledo de Souza <devs@python-telegram-bot.org> 7# 8# This program is free software: you can redistribute it and/or modify 9# it under the terms of the GNU Lesser Public License as published by 10# the Free Software Foundation, either version 3 of the License, or 11# (at your option) any later version. 12# 13# This program is distributed in the hope that it will be useful, 14# but WITHOUT ANY WARRANTY; without even the implied warranty of 15# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16# GNU Lesser Public License for more details. 17# 18# You should have received a copy of the GNU Lesser Public License 19# along with this program. If not, see [http://www.gnu.org/licenses/]. 20"""This module contains an object that represents a Telegram Chat.""" 21 22from typing import TYPE_CHECKING, Any, List, Optional, ClassVar 23 24from telegram import ChatPhoto, TelegramObject, constants 25from telegram.utils.types import JSONDict 26 27from .chatpermissions import ChatPermissions 28from .chatlocation import ChatLocation 29 30if TYPE_CHECKING: 31 from telegram import Bot, ChatMember, Message, MessageId 32 33 34class Chat(TelegramObject): 35 """This object represents a chat. 36 37 Objects of this class are comparable in terms of equality. Two objects of this class are 38 considered equal, if their :attr:`id` is equal. 39 40 Attributes: 41 id (:obj:`int`): Unique identifier for this chat. 42 type (:obj:`str`): Type of chat. 43 title (:obj:`str`): Optional. Title, for supergroups, channels and group chats. 44 username (:obj:`str`): Optional. Username. 45 first_name (:obj:`str`): Optional. First name of the other party in a private chat. 46 last_name (:obj:`str`): Optional. Last name of the other party in a private chat. 47 photo (:class:`telegram.ChatPhoto`): Optional. Chat photo. 48 bio (:obj:`str`): Optional. Bio of the other party in a private chat. Returned only in 49 :meth:`telegram.Bot.get_chat`. 50 description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats. 51 invite_link (:obj:`str`): Optional. Chat invite link, for supergroups and channel chats. 52 pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message 53 (by sending date). Returned only in :meth:`telegram.Bot.get_chat`. 54 permissions (:class:`telegram.ChatPermissions`): Optional. Default chat member permissions, 55 for groups and supergroups. Returned only in :meth:`telegram.Bot.get_chat`. 56 slow_mode_delay (:obj:`int`): Optional. For supergroups, the minimum allowed delay between 57 consecutive messages sent by each unprivileged user. Returned only in 58 :meth:`telegram.Bot.get_chat`. 59 sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set. 60 can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the 61 sticker set. 62 linked_chat_id (:obj:`int`): Optional. Unique identifier for the linked chat, i.e. the 63 discussion group identifier for a channel and vice versa; for supergroups and channel 64 chats. Returned only in :meth:`telegram.Bot.get_chat`. 65 location (:class:`telegram.ChatLocation`): Optional. For supergroups, the location to which 66 the supergroup is connected. Returned only in :meth:`telegram.Bot.get_chat`. 67 68 Args: 69 id (:obj:`int`): Unique identifier for this chat. This number may be greater than 32 bits 70 and some programming languages may have difficulty/silent defects in interpreting it. 71 But it is smaller than 52 bits, so a signed 64 bit integer or double-precision float 72 type are safe for storing this identifier. 73 type (:obj:`str`): Type of chat, can be either 'private', 'group', 'supergroup' or 74 'channel'. 75 title (:obj:`str`, optional): Title, for supergroups, channels and group chats. 76 username(:obj:`str`, optional): Username, for private chats, supergroups and channels if 77 available. 78 first_name(:obj:`str`, optional): First name of the other party in a private chat. 79 last_name(:obj:`str`, optional): Last name of the other party in a private chat. 80 photo (:class:`telegram.ChatPhoto`, optional): Chat photo. 81 Returned only in :meth:`telegram.Bot.get_chat`. 82 bio (:obj:`str`, optional): Bio of the other party in a private chat. Returned only in 83 :meth:`telegram.Bot.get_chat`. 84 description (:obj:`str`, optional): Description, for groups, supergroups and channel chats. 85 Returned only in :meth:`telegram.Bot.get_chat`. 86 invite_link (:obj:`str`, optional): Chat invite link, for groups, supergroups and channel 87 chats. Each administrator in a chat generates their own invite links, so the bot must 88 first generate the link using ``export_chat_invite_link()``. Returned only 89 in :meth:`telegram.Bot.get_chat`. 90 pinned_message (:class:`telegram.Message`, optional): The most recent pinned message 91 (by sending date). Returned only in :meth:`telegram.Bot.get_chat`. 92 permissions (:class:`telegram.ChatPermissions`): Optional. Default chat member permissions, 93 for groups and supergroups. Returned only in :meth:`telegram.Bot.get_chat`. 94 slow_mode_delay (:obj:`int`, optional): For supergroups, the minimum allowed delay between 95 consecutive messages sent by each unprivileged user. 96 Returned only in :meth:`telegram.Bot.get_chat`. 97 bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. 98 sticker_set_name (:obj:`str`, optional): For supergroups, name of group sticker set. 99 Returned only in :meth:`telegram.Bot.get_chat`. 100 can_set_sticker_set (:obj:`bool`, optional): :obj:`True`, if the bot can change group the 101 sticker set. Returned only in :meth:`telegram.Bot.get_chat`. 102 linked_chat_id (:obj:`int`, optional): Unique identifier for the linked chat, i.e. the 103 discussion group identifier for a channel and vice versa; for supergroups and channel 104 chats. Returned only in :meth:`telegram.Bot.get_chat`. 105 location (:class:`telegram.ChatLocation`, optional): For supergroups, the location to which 106 the supergroup is connected. Returned only in :meth:`telegram.Bot.get_chat`. 107 **kwargs (:obj:`dict`): Arbitrary keyword arguments. 108 109 """ 110 111 PRIVATE: ClassVar[str] = constants.CHAT_PRIVATE 112 """:const:`telegram.constants.CHAT_PRIVATE`""" 113 GROUP: ClassVar[str] = constants.CHAT_GROUP 114 """:const:`telegram.constants.CHAT_GROUP`""" 115 SUPERGROUP: ClassVar[str] = constants.CHAT_SUPERGROUP 116 """:const:`telegram.constants.CHAT_SUPERGROUP`""" 117 CHANNEL: ClassVar[str] = constants.CHAT_CHANNEL 118 """:const:`telegram.constants.CHAT_CHANNEL`""" 119 120 def __init__( 121 self, 122 id: int, 123 type: str, 124 title: str = None, 125 username: str = None, 126 first_name: str = None, 127 last_name: str = None, 128 bot: 'Bot' = None, 129 photo: ChatPhoto = None, 130 description: str = None, 131 invite_link: str = None, 132 pinned_message: 'Message' = None, 133 permissions: ChatPermissions = None, 134 sticker_set_name: str = None, 135 can_set_sticker_set: bool = None, 136 slow_mode_delay: int = None, 137 bio: str = None, 138 linked_chat_id: int = None, 139 location: ChatLocation = None, 140 **_kwargs: Any, 141 ): 142 # Required 143 self.id = int(id) 144 self.type = type 145 # Optionals 146 self.title = title 147 self.username = username 148 self.first_name = first_name 149 self.last_name = last_name 150 # TODO: Remove (also from tests), when Telegram drops this completely 151 self.all_members_are_administrators = _kwargs.get('all_members_are_administrators') 152 self.photo = photo 153 self.bio = bio 154 self.description = description 155 self.invite_link = invite_link 156 self.pinned_message = pinned_message 157 self.permissions = permissions 158 self.slow_mode_delay = slow_mode_delay 159 self.sticker_set_name = sticker_set_name 160 self.can_set_sticker_set = can_set_sticker_set 161 self.linked_chat_id = linked_chat_id 162 self.location = location 163 164 self.bot = bot 165 self._id_attrs = (self.id,) 166 167 @property 168 def link(self) -> Optional[str]: 169 """:obj:`str`: Convenience property. If the chat has a :attr:`username`, returns a t.me 170 link of the chat.""" 171 if self.username: 172 return f"https://t.me/{self.username}" 173 return None 174 175 @classmethod 176 def de_json(cls, data: JSONDict, bot: 'Bot') -> Optional['Chat']: 177 data = cls.parse_data(data) 178 179 if not data: 180 return None 181 182 data['photo'] = ChatPhoto.de_json(data.get('photo'), bot) 183 from telegram import Message # pylint: disable=C0415 184 185 data['pinned_message'] = Message.de_json(data.get('pinned_message'), bot) 186 data['permissions'] = ChatPermissions.de_json(data.get('permissions'), bot) 187 data['location'] = ChatLocation.de_json(data.get('location'), bot) 188 189 return cls(bot=bot, **data) 190 191 def leave(self, *args: Any, **kwargs: Any) -> bool: 192 """Shortcut for:: 193 194 bot.leave_chat(update.effective_chat.id, *args, **kwargs) 195 196 Returns: 197 :obj:`bool` If the action was sent successfully. 198 199 """ 200 return self.bot.leave_chat(self.id, *args, **kwargs) 201 202 def get_administrators(self, *args: Any, **kwargs: Any) -> List['ChatMember']: 203 """Shortcut for:: 204 205 bot.get_chat_administrators(update.effective_chat.id, *args, **kwargs) 206 207 Returns: 208 List[:class:`telegram.ChatMember`]: A list of administrators in a chat. An Array of 209 :class:`telegram.ChatMember` objects that contains information about all 210 chat administrators except other bots. If the chat is a group or a supergroup 211 and no administrators were appointed, only the creator will be returned. 212 213 """ 214 return self.bot.get_chat_administrators(self.id, *args, **kwargs) 215 216 def get_members_count(self, *args: Any, **kwargs: Any) -> int: 217 """Shortcut for:: 218 219 bot.get_chat_members_count(update.effective_chat.id, *args, **kwargs) 220 221 Returns: 222 :obj:`int` 223 224 """ 225 return self.bot.get_chat_members_count(self.id, *args, **kwargs) 226 227 def get_member(self, *args: Any, **kwargs: Any) -> 'ChatMember': 228 """Shortcut for:: 229 230 bot.get_chat_member(update.effective_chat.id, *args, **kwargs) 231 232 Returns: 233 :class:`telegram.ChatMember` 234 235 """ 236 return self.bot.get_chat_member(self.id, *args, **kwargs) 237 238 def kick_member(self, *args: Any, **kwargs: Any) -> bool: 239 """Shortcut for:: 240 241 bot.kick_chat_member(update.effective_chat.id, *args, **kwargs) 242 243 Returns: 244 :obj:`bool`: If the action was sent successfully. 245 246 Note: 247 This method will only work if the `All Members Are Admins` setting is off in the 248 target group. Otherwise members may only be removed by the group's creator or by the 249 member that added them. 250 251 """ 252 return self.bot.kick_chat_member(self.id, *args, **kwargs) 253 254 def unban_member(self, *args: Any, **kwargs: Any) -> bool: 255 """Shortcut for:: 256 257 bot.unban_chat_member(update.effective_chat.id, *args, **kwargs) 258 259 Returns: 260 :obj:`bool`: If the action was sent successfully. 261 262 """ 263 return self.bot.unban_chat_member(self.id, *args, **kwargs) 264 265 def set_permissions(self, *args: Any, **kwargs: Any) -> bool: 266 """Shortcut for:: 267 268 bot.set_chat_permissions(update.effective_chat.id, *args, **kwargs) 269 270 Returns: 271 :obj:`bool`: If the action was sent successfully. 272 273 """ 274 return self.bot.set_chat_permissions(self.id, *args, **kwargs) 275 276 def set_administrator_custom_title(self, *args: Any, **kwargs: Any) -> bool: 277 """Shortcut for:: 278 279 bot.set_chat_administrator_custom_title(update.effective_chat.id, *args, **kwargs) 280 281 Returns: 282 :obj:`bool`: If the action was sent successfully. 283 284 """ 285 return self.bot.set_chat_administrator_custom_title(self.id, *args, **kwargs) 286 287 def pin_message(self, *args: Any, **kwargs: Any) -> bool: 288 """Shortcut for:: 289 290 bot.pin_chat_message(chat_id=update.effective_chat.id, 291 *args, 292 **kwargs) 293 294 Returns: 295 :obj:`bool`: On success, :obj:`True` is returned. 296 297 """ 298 return self.bot.pin_chat_message(self.id, *args, **kwargs) 299 300 def unpin_message(self, *args: Any, **kwargs: Any) -> bool: 301 """Shortcut for:: 302 303 bot.unpin_chat_message(chat_id=update.effective_chat.id, 304 *args, 305 **kwargs) 306 307 Returns: 308 :obj:`bool`: On success, :obj:`True` is returned. 309 310 """ 311 return self.bot.unpin_chat_message(self.id, *args, **kwargs) 312 313 def unpin_all_messages(self, *args: Any, **kwargs: Any) -> bool: 314 """Shortcut for:: 315 316 bot.unpin_all_chat_messages(chat_id=update.effective_chat.id, 317 *args, 318 **kwargs) 319 320 Returns: 321 :obj:`bool`: On success, :obj:`True` is returned. 322 323 """ 324 return self.bot.unpin_all_chat_messages(chat_id=self.id, *args, **kwargs) 325 326 def send_message(self, *args: Any, **kwargs: Any) -> 'Message': 327 """Shortcut for:: 328 329 bot.send_message(update.effective_chat.id, *args, **kwargs) 330 331 Returns: 332 :class:`telegram.Message`: On success, instance representing the message posted. 333 334 """ 335 return self.bot.send_message(self.id, *args, **kwargs) 336 337 def send_media_group(self, *args: Any, **kwargs: Any) -> List['Message']: 338 """Shortcut for:: 339 340 bot.send_media_group(update.effective_chat.id, *args, **kwargs) 341 342 Returns: 343 List[:class:`telegram.Message`:] On success, instance representing the message posted. 344 345 """ 346 return self.bot.send_media_group(self.id, *args, **kwargs) 347 348 def send_chat_action(self, *args: Any, **kwargs: Any) -> bool: 349 """Shortcut for:: 350 351 bot.send_chat_action(update.effective_chat.id, *args, **kwargs) 352 353 Returns: 354 :obj:`True`: On success. 355 356 """ 357 return self.bot.send_chat_action(self.id, *args, **kwargs) 358 359 send_action = send_chat_action 360 """Alias for :attr:`send_chat_action`""" 361 362 def send_photo(self, *args: Any, **kwargs: Any) -> 'Message': 363 """Shortcut for:: 364 365 bot.send_photo(update.effective_chat.id, *args, **kwargs) 366 367 Returns: 368 :class:`telegram.Message`: On success, instance representing the message posted. 369 370 """ 371 return self.bot.send_photo(self.id, *args, **kwargs) 372 373 def send_contact(self, *args: Any, **kwargs: Any) -> 'Message': 374 """Shortcut for:: 375 376 bot.send_contact(update.effective_chat.id, *args, **kwargs) 377 378 Returns: 379 :class:`telegram.Message`: On success, instance representing the message posted. 380 381 """ 382 return self.bot.send_contact(self.id, *args, **kwargs) 383 384 def send_audio(self, *args: Any, **kwargs: Any) -> 'Message': 385 """Shortcut for:: 386 387 bot.send_audio(update.effective_chat.id, *args, **kwargs) 388 389 Returns: 390 :class:`telegram.Message`: On success, instance representing the message posted. 391 392 """ 393 return self.bot.send_audio(self.id, *args, **kwargs) 394 395 def send_document(self, *args: Any, **kwargs: Any) -> 'Message': 396 """Shortcut for:: 397 398 bot.send_document(update.effective_chat.id, *args, **kwargs) 399 400 Returns: 401 :class:`telegram.Message`: On success, instance representing the message posted. 402 403 """ 404 return self.bot.send_document(self.id, *args, **kwargs) 405 406 def send_dice(self, *args: Any, **kwargs: Any) -> 'Message': 407 """Shortcut for:: 408 409 bot.send_dice(update.effective_chat.id, *args, **kwargs) 410 411 Returns: 412 :class:`telegram.Message`: On success, instance representing the message posted. 413 414 """ 415 return self.bot.send_dice(self.id, *args, **kwargs) 416 417 def send_game(self, *args: Any, **kwargs: Any) -> 'Message': 418 """Shortcut for:: 419 420 bot.send_game(update.effective_chat.id, *args, **kwargs) 421 422 Returns: 423 :class:`telegram.Message`: On success, instance representing the message posted. 424 425 """ 426 return self.bot.send_game(self.id, *args, **kwargs) 427 428 def send_invoice(self, *args: Any, **kwargs: Any) -> 'Message': 429 """Shortcut for:: 430 431 bot.send_invoice(update.effective_chat.id, *args, **kwargs) 432 433 Returns: 434 :class:`telegram.Message`: On success, instance representing the message posted. 435 436 """ 437 return self.bot.send_invoice(self.id, *args, **kwargs) 438 439 def send_location(self, *args: Any, **kwargs: Any) -> 'Message': 440 """Shortcut for:: 441 442 bot.send_location(update.effective_chat.id, *args, **kwargs) 443 444 Returns: 445 :class:`telegram.Message`: On success, instance representing the message posted. 446 447 """ 448 return self.bot.send_location(self.id, *args, **kwargs) 449 450 def send_animation(self, *args: Any, **kwargs: Any) -> 'Message': 451 """Shortcut for:: 452 453 bot.send_animation(update.effective_chat.id, *args, **kwargs) 454 455 Returns: 456 :class:`telegram.Message`: On success, instance representing the message posted. 457 458 """ 459 return self.bot.send_animation(self.id, *args, **kwargs) 460 461 def send_sticker(self, *args: Any, **kwargs: Any) -> 'Message': 462 """Shortcut for:: 463 464 bot.send_sticker(update.effective_chat.id, *args, **kwargs) 465 466 Returns: 467 :class:`telegram.Message`: On success, instance representing the message posted. 468 469 """ 470 return self.bot.send_sticker(self.id, *args, **kwargs) 471 472 def send_venue(self, *args: Any, **kwargs: Any) -> 'Message': 473 """Shortcut for:: 474 475 bot.send_venue(update.effective_chat.id, *args, **kwargs) 476 477 Returns: 478 :class:`telegram.Message`: On success, instance representing the message posted. 479 480 """ 481 return self.bot.send_venue(self.id, *args, **kwargs) 482 483 def send_video(self, *args: Any, **kwargs: Any) -> 'Message': 484 """Shortcut for:: 485 486 bot.send_video(update.effective_chat.id, *args, **kwargs) 487 488 Returns: 489 :class:`telegram.Message`: On success, instance representing the message posted. 490 491 """ 492 return self.bot.send_video(self.id, *args, **kwargs) 493 494 def send_video_note(self, *args: Any, **kwargs: Any) -> 'Message': 495 """Shortcut for:: 496 497 bot.send_video_note(update.effective_chat.id, *args, **kwargs) 498 499 Returns: 500 :class:`telegram.Message`: On success, instance representing the message posted. 501 502 """ 503 return self.bot.send_video_note(self.id, *args, **kwargs) 504 505 def send_voice(self, *args: Any, **kwargs: Any) -> 'Message': 506 """Shortcut for:: 507 508 bot.send_voice(update.effective_chat.id, *args, **kwargs) 509 510 Returns: 511 :class:`telegram.Message`: On success, instance representing the message posted. 512 513 """ 514 return self.bot.send_voice(self.id, *args, **kwargs) 515 516 def send_poll(self, *args: Any, **kwargs: Any) -> 'Message': 517 """Shortcut for:: 518 519 bot.send_poll(update.effective_chat.id, *args, **kwargs) 520 521 Returns: 522 :class:`telegram.Message`: On success, instance representing the message posted. 523 524 """ 525 return self.bot.send_poll(self.id, *args, **kwargs) 526 527 def send_copy(self, *args: Any, **kwargs: Any) -> 'MessageId': 528 """Shortcut for:: 529 530 bot.copy_message(chat_id=update.effective_chat.id, *args, **kwargs) 531 532 Returns: 533 :class:`telegram.Message`: On success, instance representing the message posted. 534 535 """ 536 return self.bot.copy_message(chat_id=self.id, *args, **kwargs) 537 538 def copy_message(self, *args: Any, **kwargs: Any) -> 'MessageId': 539 """Shortcut for:: 540 541 bot.copy_message(from_chat_id=update.effective_chat.id, *args, **kwargs) 542 543 Returns: 544 :class:`telegram.Message`: On success, instance representing the message posted. 545 546 """ 547 return self.bot.copy_message(from_chat_id=self.id, *args, **kwargs) 548