feat: add bulk banning (#1695)

* chore: bump discord_typings vbersion

* feat: add bulk banning

Author: AstreaTSS

interactions/__init__.py

@@ -83,6 +83,7 @@
     BrandColors,
     BrandColours,
     Buckets,
+    BulkBanResponse,
     Button,
     ButtonStyle,
     CallbackObject,
@@ -408,6 +409,7 @@
     "BrandColors",
     "BrandColours",
     "Buckets",
+    "BulkBanResponse",
     "Button",
     "ButtonStyle",
     "CallbackObject",

interactions/api/http/http_requests/guild.py

@@ -299,6 +299,32 @@ async def remove_guild_ban(
             Route("DELETE", "/guilds/{guild_id}/bans/{user_id}", guild_id=guild_id, user_id=user_id), reason=reason
         )
 
+    async def bulk_guild_ban(
+        self,
+        guild_id: "Snowflake_Type",
+        user_ids: "list[Snowflake_Type]",
+        delete_message_seconds: int = 0,
+        reason: str | None = None,
+    ) -> discord_typings.BulkBanData:
+        """
+        Ban a list of users from the guild.
+
+        Args:
+            guild_id: The ID of the guild to create the ban in
+            user_ids: List of user ids to ban (max 200)
+            delete_message_seconds: Number of seconds to delete messages for (0-604800)
+            reason: The reason for this action
+
+        Returns:
+            Bulk ban object
+
+        """
+        payload = {"delete_message_days": delete_message_seconds, "user_ids": user_ids}
+        result = await self.request(
+            Route("POST", "/guilds/{guild_id}/bulk-ban", guild_id=guild_id), payload=payload, reason=reason
+        )
+        return cast(discord_typings.BulkBanData, result)
+
     async def get_guild_prune_count(
         self,
         guild_id: "Snowflake_Type",

interactions/models/__init__.py

@@ -29,6 +29,7 @@
     BaseUser,
     BrandColors,
     BrandColours,
+    BulkBanResponse,
     Button,
     ButtonStyle,
     ChannelFlags,
@@ -358,6 +359,7 @@
     "BrandColors",
     "BrandColours",
     "Buckets",
+    "BulkBanResponse",
     "Button",
     "ButtonStyle",
     "CallbackObject",

interactions/models/discord/__init__.py

@@ -128,6 +128,7 @@
     AuditLogEntry,
     AuditLogHistory,
     BaseGuild,
+    BulkBanResponse,
     Guild,
     GuildBan,
     GuildIntegration,
@@ -205,6 +206,7 @@
     "BaseUser",
     "BrandColors",
     "BrandColours",
+    "BulkBanResponse",
     "Button",
     "ButtonStyle",
     "ChannelFlags",

interactions/models/discord/guild.py

@@ -61,6 +61,7 @@
 
 __all__ = (
     "GuildBan",
+    "BulkBanResponse",
     "BaseGuild",
     "GuildWelcome",
     "GuildPreview",
@@ -85,6 +86,34 @@ class GuildBan:
     """The banned user"""
 
 
+@attrs.define(eq=False, order=False, hash=False, kw_only=True)
+class BulkBanResponse(ClientObject):
+    _banned_users: list[Snowflake_Type] = attrs.field(repr=False, converter=to_snowflake_list)
+    """List of user IDs that were successfully banned."""
+    _failed_users: list[Snowflake_Type] = attrs.field(repr=False, converter=to_snowflake_list)
+    """List of user IDs that were not banned."""
+
+    @property
+    def banned_users(self) -> List["models.User | None"]:
+        """List of users that were successfully banned."""
+        return [self.client.cache.get_user(u_id) for u_id in self._banned_users]
+
+    @property
+    def failed_users(self) -> List["models.User | None"]:
+        """List of users that were not banned."""
+        return [self.client.cache.get_user(u_id) for u_id in self._failed_users]
+
+    @property
+    def failed_user_ids(self) -> List[Snowflake_Type]:
+        """List of user IDs that were not banned."""
+        return self._failed_users
+
+    @property
+    def banned_user_ids(self) -> List[Snowflake_Type]:
+        """List of user IDs that were successfully banned."""
+        return self._banned_users
+
+
 @attrs.define(eq=False, order=False, hash=False, kw_only=True)
 class BaseGuild(DiscordObject):
     name: str = attrs.field(repr=True)
@@ -1748,6 +1777,29 @@ async def ban(
             delete_message_seconds = delete_message_days * 3600
         await self._client.http.create_guild_ban(self.id, to_snowflake(user), delete_message_seconds, reason=reason)
 
+    async def bulk_ban(
+        self,
+        users: List[Union["models.User", "models.Member", Snowflake_Type]],
+        delete_message_seconds: int = 0,
+        reason: Optional[str] = None,
+    ) -> BulkBanResponse:
+        """
+        Bans a list of users from the guild.
+
+        !!! note
+            You must have the `ban members` permission
+
+        Args:
+            user: The users to ban
+            delete_message_seconds: How many seconds worth of messages to remove
+            reason: The reason for the ban
+
+        """
+        result = await self.client.http.bulk_guild_ban(
+            self.id, [to_snowflake(user) for user in users], delete_message_seconds, reason=reason
+        )
+        return BulkBanResponse.from_dict(result, self.client)
+
     async def fetch_ban(self, user: Union["models.User", "models.Member", Snowflake_Type]) -> Optional[GuildBan]:
         """
         Fetches the ban information for the specified user in the guild. You must have the `ban members` permission.