feat: Support bulk banning in guilds

CHANGELOG.md

@@ -20,6 +20,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2417](https://github.com/Pycord-Development/pycord/pull/2417))
 - Added `Guild.search_members`.
   ([#2418](https://github.com/Pycord-Development/pycord/pull/2418))
+- Added bulk banning up to 200 users through `Guild.ban`.
+  ([#2421](https://github.com/Pycord-Development/pycord/pull/2421))
 
 ### Fixed
 

discord/guild.py

@@ -3073,25 +3073,35 @@ async def kick(self, user: Snowflake, *, reason: str | None = None) -> None:
 
     async def ban(
         self,
-        user: Snowflake,
-        *,
+        *users: Snowflake,
         delete_message_seconds: int | None = None,
         delete_message_days: Literal[0, 1, 2, 3, 4, 5, 6, 7] | None = None,
         reason: str | None = None,
-    ) -> None:
-        """|coro|
+    ) -> list[list[Snowflake], list[Snowflake]] | None:
+        r"""|coro|
 
-        Bans a user from the guild.
+        Bans user(s) from the guild.
 
-        The user must meet the :class:`abc.Snowflake` abc.
+        The user(s) must meet the :class:`abc.Snowflake` abc.
 
         You must have the :attr:`~Permissions.ban_members` permission to
         do this.
 
+        Example Usage: ::
+
+            # Ban a single user
+            await guild.ban(user, reason="Spam")
+
+            # Ban multiple users
+            successes, failures = await guild.ban(user1, user2, user3, ..., reason="Raid")
+
+            # Ban a list of users
+            successes, failures = await guild.ban(*users)
+
         Parameters
         ----------
-        user: :class:`abc.Snowflake`
-            The user to ban from their guild.
+        \*users: :class:`abc.Snowflake`
+            An argument list of users to ban from the guild, up to 200.
         delete_message_seconds: Optional[:class:`int`]
             The number of seconds worth of messages to delete from
             the user in the guild. The minimum is 0 and the maximum
@@ -3100,14 +3110,21 @@ async def ban(
             ***Deprecated parameter***, same as ``delete_message_seconds`` but
             is used for days instead.
         reason: Optional[:class:`str`]
-            The reason the user got banned.
+            The reason the users got banned.
+
+        Returns
+        -------
+        Optional[List[List[:class:`abc.Snowflake`], List[:class:`abc.Snowflake`]]]
+            If banning a single member, returns nothing. Otherwise, returns two lists: the first contains members that were successfully banned, while the second is members that could not be banned.
 
         Raises
         ------
+        ValueError
+            You tried to ban more than 200 users.
         Forbidden
             You do not have the proper permissions to ban.
         HTTPException
-            Banning failed.
+            No users were banned.
         """
         if delete_message_seconds and delete_message_days:
             raise TypeError(
@@ -3121,9 +3138,29 @@ async def ban(
                 "delete_message_seconds must be between 0 and 604800 seconds."
             )
 
-        await self._state.http.ban(
-            user.id, self.id, delete_message_seconds, delete_message_days, reason=reason
-        )
+        if len(users) == 1:
+            await self._state.http.ban(
+                users[0].id,
+                self.id,
+                delete_message_seconds,
+                delete_message_days,
+                reason=reason,
+            )
+        elif len(users) > 200:
+            raise ValueError(
+                "The number of users to be banned must be between 1 and 200."
+            )
+        else:
+            data = await self._state.http.bulk_ban(
+                [u.id for u in users],
+                self.id,
+                delete_message_seconds,
+                delete_message_days,
+                reason=reason,
+            )
+            banned = [u for u in users if str(u.id) in data["banned_users"]]
+            failed = [u for u in users if str(u.id) in data["failed_users"]]
+            return banned, failed
 
     async def unban(self, user: Snowflake, *, reason: str | None = None) -> None:
         """|coro|

discord/http.py

@@ -931,6 +931,35 @@ def ban(
 
         return self.request(r, params=params, reason=reason)
 
+    def bulk_ban(
+        self,
+        user_ids: list[Snowflake],
+        guild_id: Snowflake,
+        delete_message_seconds: int = None,
+        delete_message_days: int = None,
+        reason: str | None = None,
+    ) -> Response[guild.GuildBulkBan]:
+        r = Route(
+            "POST",
+            "/guilds/{guild_id}/bulk-ban",
+            guild_id=guild_id,
+        )
+        payload = {
+            "user_ids": user_ids,
+        }
+        if delete_message_seconds:
+            payload["delete_message_seconds"] = delete_message_seconds
+        elif delete_message_days:
+            warn_deprecated(
+                "delete_message_days",
+                "delete_message_seconds",
+                "2.2",
+                reference="https://github.com/discord/discord-api-docs/pull/5219",
+            )
+            payload["delete_message_days"] = delete_message_days
+
+        return self.request(r, json=payload, reason=reason)
+
     def unban(
         self, user_id: Snowflake, guild_id: Snowflake, *, reason: str | None = None
     ) -> Response[None]:

discord/types/guild.py

@@ -185,3 +185,8 @@ class RolePositionUpdate(TypedDict, total=False):
 
 class GuildMFAModify(TypedDict):
     level: Literal[0, 1]
+
+
+class GuildBulkBan(TypedDict):
+    banned_users: list[Snowflake]
+    failed_users: list[Snowflake]