feat: option to defer without raising errors

[mifuyutsuki]

Pull Request Type

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

Description

Add a bool kwarg suppress_error (default False) to defer() (often ctx.defer()) in different instances of InteractionContext. If enabled, deferring an interaction response again will not raise an error, which is the current behavior of ctx.defer().

One example use case of this feature, which I use in a bot of mine, is using auto_defer(time_until_defer=...) and ctx.defer() together, making the command defer after either a certain point or a set time, whichever is reached first.

Technical Description

This feature moves/renames the current defer() to _defer() (note the underscore). The new defer() is a wrapper for _defer(), which would suppress relevant errors (AlreadyDeferred, AlreadyResponded, and HTTPException) using contextlib.suppress(). A similar method of error suppression is already used by AutoDefer.

Changes

• Add bool kwarg suppress_error to defer()
  • Default is False in line with current behavior
• Add error suppression logic in defer()
  • Affects InteractionContext, ComponentContext, ContextMenuContext, ModalContext, and HybridContext
• Bonus: add docstring note in defer() regarding the method overriding ephemeral response settings

Related Issues

Test Scenarios

Use the following callback coroutine to an interaction command (slash command, component, context menu, modal, hybrid slash command). Tested on all five.

async def test_cmd(ctx):
  await ctx.defer()
  try:
    await ctx.defer(suppress_error=True)
  except Exception as e:
    await ctx.send(f"Error raised: {type(e)}.")
  else:
    await ctx.send(f"No error.")

If suppress_error=False or unspecified: Command responds with "Error raised" for AlreadyDeferred. If suppress_error=True: Command responds with "No error".

Python Compatibility

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

Checklist

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