diff --git a/docs/source/api/bound-methods.rst b/docs/source/api/bound-methods.rst index d129ad16..6a1cf1c3 100644 --- a/docs/source/api/bound-methods.rst +++ b/docs/source/api/bound-methods.rst @@ -70,6 +70,10 @@ Chat - :meth:`~Chat.set_title` - :meth:`~Chat.set_description` - :meth:`~Chat.set_photo` + - :meth:`~Chat.kick_member` + - :meth:`~Chat.unban_member` + - :meth:`~Chat.restrict_member` + - :meth:`~Chat.promote_member` User ^^^^ @@ -140,6 +144,10 @@ Details .. automethod:: Chat.set_title() .. automethod:: Chat.set_description) .. automethod:: Chat.set_photo() +.. automethod:: Chat.kick_member() +.. automethod:: Chat.unban_member() +.. automethod:: Chat.restrict_member() +.. automethod:: Chat.promote_member() .. User .. automethod:: User.archive() diff --git a/pyrogram/client/types/user_and_chats/chat.py b/pyrogram/client/types/user_and_chats/chat.py index e99bccea..556672d2 100644 --- a/pyrogram/client/types/user_and_chats/chat.py +++ b/pyrogram/client/types/user_and_chats/chat.py @@ -419,3 +419,258 @@ class Chat(Object): chat_id=self.id, photo=photo ) + + def kick_member( + self, + user_id: Union[int, str], + until_date: int = 0 + ) -> Union["pyrogram.Message", bool]: + """Bound method *kick_member* of :obj:`Chat`. + + Use as a shortcut for: + + .. code-block:: python + + client.kick_chat_member( + chat_id=chat_id, + user_id=user_id + ) + + Example: + .. code-block:: python + + chat.kick_member(123456789) + + Note: + In regular groups (non-supergroups), this method will only work if the "All Members Are Admins" setting is + off in the target group. Otherwise members may only be removed by the group's creator or by the member + that added them. + + Parameters: + user_id (``int`` | ``str``): + Unique identifier (int) or username (str) of the target user. + For a contact that exists in your Telegram address book you can use his phone number (str). + + until_date (``int``, *optional*): + Date when the user will be unbanned, unix time. + If user is banned for more than 366 days or less than 30 seconds from the current time they are + considered to be banned forever. Defaults to 0 (ban forever). + + Returns: + :obj:`Message` | ``bool``: On success, a service message will be returned (when applicable), otherwise, in + case a message object couldn't be returned, True is returned. + + Raises: + RPCError: In case of a Telegram RPC error. + """ + + return self._client.kick_chat_member( + chat_id=self.id, + user_id=user_id, + until_date=until_date + ) + + def unban_member( + self, + user_id: Union[int, str] + ) -> bool: + """Bound method *unban_member* of :obj:`Chat`. + + Use as a shortcut for: + + .. code-block:: python + + client.unban_chat_member( + chat_id=chat_id, + user_id=user_id + ) + + Example: + .. code-block:: python + + chat.unban_member(123456789) + + Parameters: + user_id (``int`` | ``str``): + Unique identifier (int) or username (str) of the target user. + For a contact that exists in your Telegram address book you can use his phone number (str). + + Returns: + ``bool``: True on success. + + Raises: + RPCError: In case of a Telegram RPC error. + """ + + return self._client.unban_chat_member( + chat_id=self.id, + user_id=user_id, + ) + + def restrict_member( + self, + chat_id: Union[int, str], + user_id: Union[int, str], + until_date: int = 0, + can_send_messages: bool = False, + can_send_media_messages: bool = False, + can_send_other_messages: bool = False, + can_add_web_page_previews: bool = False, + can_send_polls: bool = False, + can_change_info: bool = False, + can_invite_users: bool = False, + can_pin_messages: bool = False + ) -> "pyrogram.Chat": + """Bound method *unban_member* of :obj:`Chat`. + + Use as a shortcut for: + + .. code-block:: python + + client.restrict_chat_member( + chat_id=chat_id, + user_id=user_id + ) + + Example: + .. code-block:: python + + chat.restrict_member(123456789) + + Parameters: + user_id (``int`` | ``str``): + Unique identifier (int) or username (str) of the target user. + For a contact that exists in your Telegram address book you can use his phone number (str). + + until_date (``int``, *optional*): + Date when the user will be unbanned, unix time. + If user is banned for more than 366 days or less than 30 seconds from the current time they are + considered to be banned forever. Defaults to 0 (ban forever). + + can_send_messages (``bool``, *optional*): + Pass True, if the user can send text messages, contacts, locations and venues. + + can_send_media_messages (``bool``, *optional*): + Pass True, if the user can send audios, documents, photos, videos, video notes and voice notes, + implies can_send_messages. + + can_send_other_messages (``bool``, *optional*): + Pass True, if the user can send animations, games, stickers and use inline bots, + implies can_send_media_messages. + + can_add_web_page_previews (``bool``, *optional*): + Pass True, if the user may add web page previews to their messages, implies can_send_media_messages. + + can_send_polls (``bool``, *optional*): + Pass True, if the user can send polls, implies can_send_media_messages. + + can_change_info (``bool``, *optional*): + Pass True, if the user can change the chat title, photo and other settings. + + can_invite_users (``bool``, *optional*): + Pass True, if the user can invite new users to the chat. + + can_pin_messages (``bool``, *optional*): + Pass True, if the user can pin messages. + + Returns: + :obj:`Chat`: On success, a chat object is returned. + + Raises: + RPCError: In case of a Telegram RPC error. + """ + + return self._client.restrict_chat_member( + self, + chat_id=self.id, + user_id=user_id, + until_date=until_date, + can_send_messages=can_send_messages, + can_send_media_messages=can_send_media_messages, + can_send_other_messages=can_send_other_messages, + can_add_web_page_previews=can_add_web_page_previews, + can_send_polls=can_send_polls, + can_change_info=can_change_info, + can_invite_users=can_invite_users, + can_pin_messages=can_pin_messages + ) + + def promote_member( + chat_id: Union[int, str], + user_id: Union[int, str], + can_change_info: bool = True, + can_post_messages: bool = False, + can_edit_messages: bool = False, + can_delete_messages: bool = True, + can_restrict_members: bool = True, + can_invite_users: bool = True, + can_pin_messages: bool = False, + can_promote_members: bool = False + ) -> bool: + """Bound method *promote_member* of :obj:`Chat`. + + Use as a shortcut for: + + .. code-block:: python + + client.promote_chat_member( + chat_id=chat_id, + user_id=user_id + ) + + Example: + + .. code-block:: python + + chat.promote_member(123456789) + + Parameters: + user_id (``int`` | ``str``): + Unique identifier (int) or username (str) of the target user. + For a contact that exists in your Telegram address book you can use his phone number (str). + + can_change_info (``bool``, *optional*): + Pass True, if the administrator can change chat title, photo and other settings. + + can_post_messages (``bool``, *optional*): + Pass True, if the administrator can create channel posts, channels only. + + can_edit_messages (``bool``, *optional*): + Pass True, if the administrator can edit messages of other users and can pin messages, channels only. + + can_delete_messages (``bool``, *optional*): + Pass True, if the administrator can delete messages of other users. + + can_restrict_members (``bool``, *optional*): + Pass True, if the administrator can restrict, ban or unban chat members. + + can_invite_users (``bool``, *optional*): + Pass True, if the administrator can invite new users to the chat. + + can_pin_messages (``bool``, *optional*): + Pass True, if the administrator can pin messages, supergroups only. + + can_promote_members (``bool``, *optional*): + Pass True, if the administrator can add new administrators with a subset of his own privileges or + demote administrators that he has promoted, directly or indirectly (promoted by administrators that + were appointed by him). + + Returns: + ``bool``: True on success. + + Raises: + RPCError: In case of a Telegram RPC error. + """ + + return self._client.promote_chat_member( + chat_id=self.id, + user_id=user_id, + can_change_info=can_change_info, + can_post_messages=can_post_messages, + can_edit_messages=can_edit_messages, + can_delete_messages=can_delete_messages, + can_restrict_members=can_restrict_members, + can_invite_users=can_invite_users, + can_pin_messages=can_pin_messages, + can_promote_members=can_promote_members + )