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