feat: allow .purge to return messages

[LordOfPolls]

Pull Request Type

• Feature addition
• Bugfix
• Documentation update
• Code refactor
• Tests improvement
• CI/CD pipeline enhancement
• Other: [Replace with a description]

Description

Allows channel.purge to optionally return a list of messages instead of a message count

Changes

• Add a kwarg to .purge which tells it to return the messages deleted, otherwise normal behaviour is preserverd

Related Issues

#1390

Test Scenarios

channel = bot.get_channel(1085629305129807872)

out = await channel.purge(deletion_limit=10)
assert out == 10
out = await channel.purge(deletion_limit=10, return_messages=False)
assert out == 10
out = await channel.purge(deletion_limit=10, return_messages=True)
assert len(out) == 10
assert isinstance(out, list)
assert all(isinstance(m, interactions.Message) for m in out)

Python Compatibility

• I've ensured my code works on Python 3.10.x
• I've ensured my code works on Python 3.11.x

Checklist

• I've run the pre-commit code linter over all edited files
• I've tested my changes on supported Python versions
• I've added tests for my code, if applicable
• I've updated / added documentation, where applicable

[codecov-commenter]

Codecov Report

Patch and project coverage have no change.

Comparison is base (2f23f9f) 60.28% compared to head (8f39720) 60.28%.

❗ Your organization is not using the GitHub App Integration. As a result you may experience degraded service beginning May 15th. Please install the Github App Integration for your organization. Read more.

Additional details and impacted files

@@            Coverage Diff            @@
##           unstable    #1396   +/-   ##
=========================================
  Coverage     60.28%   60.28%           
=========================================
  Files           139      139           
  Lines         14606    14606           
=========================================
  Hits           8805     8805           
  Misses         5801     5801           

Impacted Files	Coverage Δ
interactions/models/discord/channel.py	51.74% <0.00%> (ø)

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.