From ded9c5d87b2398ba5049b7bcc31f168ead911cfd Mon Sep 17 00:00:00 2001
From: Rapptz <rapptz@gmail.com>
Date: Fri, 15 Mar 2024 18:05:35 -0400
Subject: [PATCH] Add support for bulk banning members

---
 discord/guild.py       | 58 ++++++++++++++++++++++++++++++++++++++++++
 discord/http.py        | 14 ++++++++++
 discord/types/guild.py |  5 ++++
 docs/api.rst           | 19 ++++++++++++++
 4 files changed, 96 insertions(+)

diff --git a/discord/guild.py b/discord/guild.py
index 7d639fe67..e65899a54 100644
--- a/discord/guild.py
+++ b/discord/guild.py
@@ -34,6 +34,7 @@ from typing import (
     Collection,
     Coroutine,
     Dict,
+    Iterable,
     List,
     Mapping,
     NamedTuple,
@@ -146,6 +147,11 @@ class BanEntry(NamedTuple):
     user: User
 
 
+class BulkBanResult(NamedTuple):
+    banned: List[Object]
+    failed: List[Object]
+
+
 class _GuildLimit(NamedTuple):
     emoji: int
     stickers: int
@@ -3789,6 +3795,58 @@ class Guild(Hashable):
         """
         await self._state.http.unban(user.id, self.id, reason=reason)
 
+    async def bulk_ban(
+        self,
+        users: Iterable[Snowflake],
+        *,
+        reason: Optional[str] = None,
+        delete_message_seconds: int = 86400,
+    ) -> BulkBanResult:
+        """|coro|
+
+        Bans multiple users from the guild.
+
+        The users must meet the :class:`abc.Snowflake` abc.
+
+        You must have :attr:`~Permissions.ban_members` to do this.
+
+        .. versionadded:: 2.4
+
+        Parameters
+        -----------
+        users: :class:`abc.Snowflake`
+            The user to ban from their guild.
+        delete_message_seconds: :class:`int`
+            The number of seconds worth of messages to delete from the user
+            in the guild. The minimum is 0 and the maximum is 604800 (7 days).
+            Defaults to 1 day.
+        reason: Optional[:class:`str`]
+            The reason the users got banned.
+
+        Raises
+        -------
+        Forbidden
+            You do not have the proper permissions to ban.
+        HTTPException
+            Banning failed.
+
+        Returns
+        --------
+        :class:`BulkBanResult`
+            The result of the bulk ban operation.
+        """
+
+        response = await self._state.http.bulk_ban(
+            self.id,
+            user_ids=[u.id for u in users],
+            delete_message_seconds=delete_message_seconds,
+            reason=reason,
+        )
+        return BulkBanResult(
+            banned=[Object(id=int(user_id), type=User) for user_id in response.get('banned_users', []) or []],
+            failed=[Object(id=int(user_id), type=User) for user_id in response.get('failed_users', []) or []],
+        )
+
     @property
     def vanity_url(self) -> Optional[str]:
         """Optional[:class:`str`]: The Discord vanity invite URL for this guild, if available.
diff --git a/discord/http.py b/discord/http.py
index e97bb883e..0979942a9 100644
--- a/discord/http.py
+++ b/discord/http.py
@@ -1055,6 +1055,20 @@ class HTTPClient:
         r = Route('DELETE', '/guilds/{guild_id}/bans/{user_id}', guild_id=guild_id, user_id=user_id)
         return self.request(r, reason=reason)
 
+    def bulk_ban(
+        self,
+        guild_id: Snowflake,
+        user_ids: List[Snowflake],
+        delete_message_seconds: int = 86400,
+        reason: Optional[str] = None,
+    ) -> Response[guild.BulkBanUserResponse]:
+        r = Route('POST', '/guilds/{guild_id}/bulk-ban', guild_id=guild_id)
+        payload = {
+            'user_ids': user_ids,
+            'delete_message_seconds': delete_message_seconds,
+        }
+        return self.request(r, json=payload, reason=reason)
+
     def guild_voice_state(
         self,
         user_id: Snowflake,
diff --git a/discord/types/guild.py b/discord/types/guild.py
index 95fa2d56e..ba43fbf96 100644
--- a/discord/types/guild.py
+++ b/discord/types/guild.py
@@ -185,3 +185,8 @@ class _RolePositionRequired(TypedDict):
 
 class RolePositionUpdate(_RolePositionRequired, total=False):
     position: Optional[Snowflake]
+
+
+class BulkBanUserResponse(TypedDict):
+    banned_users: Optional[List[Snowflake]]
+    failed_users: Optional[List[Snowflake]]
diff --git a/docs/api.rst b/docs/api.rst
index 095739721..f436b665b 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -4491,6 +4491,25 @@ Guild
 
         :type: :class:`User`
 
+.. class:: BulkBanResult
+
+    A namedtuple which represents the result returned from :meth:`~Guild.bulk_ban`.
+
+    .. versionadded:: 2.4
+
+    .. attribute:: banned
+
+        The list of users that were banned. The type of the list is a :class:`Object`
+        representing the user.
+
+        :type: List[:class:`Object`]
+    .. attribute:: failed
+
+        The list of users that could not be banned. The type of the list is a :class:`Object`
+        representing the user.
+
+        :type: List[:class:`Object`]
+
 
 ScheduledEvent
 ~~~~~~~~~~~~~~