Add moderation endpoints

ban, timeout, unban and send_whisper endpoints and methods added.

Author: chillymosh

docs/changelog.rst

@@ -15,6 +15,10 @@ Master
             - :func:`twitchio.PartialUser.remove_channel_moderator`
             - :func:`twitchio.PartialUser.start_raid`
             - :func:`twitchio.PartialUser.cancel_raid`
+            - :func:`twitchio.PartialUser.ban_user`
+            - :func:`twitchio.PartialUser.timeout_user`
+            - :func:`twitchio.PartialUser.unban_user`
+            - :func:`twitchio.PartialUser.send_whisper`
         - Added following new Client methods:
             - :func:`~twitchio.Client.fetch_chatters_colors`
             - :func:`~twitchio.Client.update_chatter_color`

twitchio/http.py

@@ -1036,3 +1036,30 @@ async def post_raid(self, token: str, from_broadcaster_id: str, to_broadcaster_i
     async def delete_raid(self, token: str, broadcaster_id: str):
         q = [("broadcaster_id", broadcaster_id)]
         return await self.request(Route("DELETE", "raids", query=q, token=token))
+
+    async def post_ban_timeout_user(
+        self,
+        token: str,
+        broadcaster_id: str,
+        moderator_id: str,
+        user_id: str,
+        reason: str,
+        duration: Optional[int] = None,
+    ):
+        q = [("broadcaster_id", broadcaster_id), ("moderator_id", moderator_id)]
+        body = {"data": {"user_id": user_id, "reason": reason}}
+        if duration:
+            if duration < 1 or duration > 1209600:
+                raise ValueError("Duration must be between 1 and 1209600 seconds")
+            body["data"]["duration"] = str(duration)
+        return await self.request(Route("POST", "moderation/bans", query=q, body=body, token=token))
+
+    async def delete_ban_timeout_user(
+        self,
+        token: str,
+        broadcaster_id: str,
+        moderator_id: str,
+        user_id: str,
+    ):
+        q = [("broadcaster_id", broadcaster_id), ("moderator_id", moderator_id), ("user_id", user_id)]
+        return await self.request(Route("DELETE", "moderation/bans", query=q, token=token))

twitchio/models.py

@@ -348,6 +348,8 @@ def __repr__(self):
 
 class BanEvent:
     """
+    This has been deprecated.
+
     Represents a user being banned from a channel.
 
     Attributes
@@ -1605,3 +1607,62 @@ def __init__(self, data: dict):
 
     def __repr__(self):
         return f"<Raid created_at={self.created_at} is_mature={self.is_mature}>"
+
+
+class Ban:
+    """
+    Represents a ban for a broadcaster / channel
+
+    Attributes
+    -----------
+    broadcaster: :class:`~twitchio.PartialUser`
+        The broadcaster whose chat room the user was banned from chatting in.
+    moderator: :class:`~twitchio.PartialUser`
+        The moderator that banned the user.
+    user: :class:`~twitchio.PartialUser`
+        The user that was banned.
+    created_at: :class:`datetime.datetime`
+        Date and time of when the ban was created.
+    """
+
+    __slots__ = ("broadcaster", "moderator", "user", "created_at")
+
+    def __init__(self, http: "TwitchHTTP", data: dict):
+        self.broadcaster = PartialUser(http, data["broadcaster_id"], None)
+        self.moderator = PartialUser(http, data["moderator_id"], None)
+        self.user = PartialUser(http, data["user_id"], None)
+        self.created_at: datetime.datetime = parse_timestamp(data["created_at"])
+
+    def __repr__(self):
+        return f"<Ban broadcaster={self.broadcaster} user={self.user} created_at={self.created_at}>"
+
+
+class Timeout:
+    """
+    Represents a timeout for a broadcaster / channel
+
+    Attributes
+    -----------
+    broadcaster: :class:`~twitchio.PartialUser`
+        The broadcaster whose chat room the user was timed out from chatting in.
+    moderator: :class:`~twitchio.PartialUser`
+        The moderator that timed the user out.
+    user: :class:`~twitchio.PartialUser`
+        The user that was timed out.
+    created_at: :class:`datetime.datetime`
+        Date and time of when the timeout was created.
+    end_time: :class:`datetime.datetime`
+        Date and time of when the timeout will end.
+    """
+
+    __slots__ = ("broadcaster", "moderator", "user", "created_at", "end_time")
+
+    def __init__(self, http: "TwitchHTTP", data: dict):
+        self.broadcaster = PartialUser(http, data["broadcaster_id"], None)
+        self.moderator = PartialUser(http, data["moderator_id"], None)
+        self.user = PartialUser(http, data["user_id"], None)
+        self.created_at: datetime.datetime = parse_timestamp(data["created_at"])
+        self.end_time: datetime.datetime = parse_timestamp(data["end_time"])
+
+    def __repr__(self):
+        return f"<Timeout broadcaster={self.broadcaster} user={self.user} created_at={self.created_at} end_time={self.end_time}>"

twitchio/user.py

@@ -368,6 +368,8 @@ async def fetch_bans(self, token: str, userids: List[Union[str, int]] = None) ->
     async def fetch_ban_events(self, token: str, userids: List[int] = None):
         """|coro|
 
+        This has been deprecated and will be removed in a future release.
+
         Fetches ban/unban events from the User's channel.
 
         Parameters
@@ -1301,6 +1303,128 @@ async def cancel_raid(self, token: str):
 
         await self._http.delete_raid(broadcaster_id=str(self.id), token=token)
 
+    async def ban_user(self, token: str, moderator_id: int, user_id, reason: str):
+        """|coro|
+
+        Bans a user from the channel/broadcaster.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            An oauth user access token with the ``moderator:manage:banned_users`` scope
+        moderator_id: :class:`int`
+            The ID of a user that has permission to moderate the broadcaster's chat room.
+            If the broadcaster wants to ban the user set this parameter to the broadcaster's ID.
+        user_id: :class:`int`
+            The ID of the user to ban.
+        reason: :class:`str`
+            The reason for the ban.
+
+        Returns
+        --------
+        :class:`twitchio.Ban`
+        """
+        from .models import Ban
+
+        data = await self._http.post_ban_timeout_user(
+            broadcaster_id=str(self.id),
+            moderator_id=str(moderator_id),
+            user_id=str(user_id),
+            reason=reason,
+            token=token,
+        )
+        return Ban(self._http, data[0])
+
+    async def timeout_user(self, token: str, moderator_id: int, user_id: int, duration: int, reason: str):
+        """|coro|
+
+        Timeouts a user from the channel/broadcaster.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            An oauth user access token with the ``moderator:manage:banned_users`` scope
+        moderator_id: :class:`int`
+            The ID of a user that has permission to moderate the broadcaster's chat room.
+            If the broadcaster wants to timeout the user set this parameter to the broadcaster's ID.
+        duration: :class:`int`
+            The duration of the timeout in seconds.
+            The minimum timeout is 1 second and the maximum is 1,209,600 seconds (2 weeks).
+            To end a user's timeout early, set this field to 1, or send an Unban user request.
+        reason: :class:`str`
+            The reason for the timeout.
+
+        Returns
+        --------
+        :class:`twitchio.Timeout`
+        """
+        from .models import Timeout
+
+        data = await self._http.post_ban_timeout_user(
+            broadcaster_id=str(self.id),
+            moderator_id=str(moderator_id),
+            user_id=str(user_id),
+            duration=duration,
+            reason=reason,
+            token=token,
+        )
+        return Timeout(self._http, data[0])
+
+    async def unban_user(self, token: str, moderator_id: int, user_id):
+        """|coro|
+
+        Unbans a user or removes a timeout from the channel/broadcaster.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            An oauth user access token with the ``moderator:manage:banned_users`` scope
+        moderator_id: :class:`int`
+            The ID of a user that has permission to moderate the broadcaster's chat room.
+            If the broadcaster wants to ban the user set this parameter to the broadcaster's ID.
+        user_id: :class:`int`
+            The ID of the user to unban.
+
+        Returns
+        --------
+        None
+        """
+
+        await self._http.delete_ban_timeout_user(
+            broadcaster_id=str(self.id),
+            moderator_id=str(moderator_id),
+            user_id=str(user_id),
+            token=token,
+        )
+
+    async def send_whisper(self, token: str, user_id: int, message: str):
+        """|coro|
+
+        Sends a whisper to a user.
+        Important Notes:
+        - The user sending the whisper must have a verified phone number.
+        - The API may silently drop whispers that it suspects of violating Twitch policies.
+        - You may whisper to a maximum of 40 unique recipients per day. Within the per day limit.
+        - You may whisper a maximum of 3 whispers per second and a maximum of 100 whispers per minute.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            An oauth user token with the ``user:manage:whispers`` scope.
+        user_id: :class:`int`
+            The ID of the user to send the whisper to.
+        message: :class:`str`
+            The message to send.
+            500 characters if the user you're sending the message to hasn't whispered you before.
+            10,000 characters if the user you're sending the message to has whispered you before.
+
+        Returns
+        --------
+        None
+        """
+
+        await self._http.post_whisper(token=token, from_user_id=str(self.id), to_user_id=str(user_id), message=message)
+
 
 class BitLeaderboardUser(PartialUser):