feat: allow .purge to return messages (#1396)

Closes #1390

Author: LordOfPolls

interactions/models/discord/channel.py

@@ -404,11 +404,12 @@ async def purge(
         search_limit: int = 100,
         predicate: Callable[["models.Message"], bool] = MISSING,
         avoid_loading_msg: bool = True,
+        return_messages: bool = False,
         before: Optional[Snowflake_Type] = MISSING,
         after: Optional[Snowflake_Type] = MISSING,
         around: Optional[Snowflake_Type] = MISSING,
         reason: Absent[Optional[str]] = MISSING,
-    ) -> int:
+    ) -> int | List["models.Message"]:
         """
         Bulk delete messages within a channel. If a `predicate` is provided, it will be used to determine which messages to delete, otherwise all messages will be deleted within the `deletion_limit`.
 
@@ -424,6 +425,7 @@ async def purge(
             search_limit: How many messages to search through
             predicate: A function that returns True or False, and takes a message as an argument
             avoid_loading_msg: Should the bot attempt to avoid deleting its own loading messages (recommended enabled)
+            return_messages: Should the bot return the messages that were deleted
             before: Search messages before this ID
             after: Search messages after this ID
             around: Search messages around this ID
@@ -461,13 +463,13 @@ def predicate(m) -> bool:
                 # message is too old to be purged
                 continue
 
-            to_delete.append(message.id)
+            to_delete.append(message)
 
-        count = len(to_delete)
+        out = to_delete.copy()
         while len(to_delete):
-            iteration = [to_delete.pop() for i in range(min(100, len(to_delete)))]
+            iteration = [to_delete.pop().id for i in range(min(100, len(to_delete)))]
             await self.delete_messages(iteration, reason=reason)
-        return count
+        return out if return_messages else len(out)
 
     async def trigger_typing(self) -> None:
         """Trigger a typing animation in this channel."""