feat: option to hide paginator buttons on stop/timeout

[mifuyutsuki]

Pull Request Type

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

Description

Adds a bool attribute hide_buttons_on_stop to Paginator in interactions.ext.paginators. If set to True, the paginator will hide/clear all of its components on (1) a timeout or (2) a call to Paginator.stop(). Otherwise, the components are disabled, which is the current (and with this PR, default) behavior of the paginator.

Changes

• Add bool attribute hide_buttons_on_stop to Paginator
• Edited Paginator.create_components()
  • The method short-circuits to return [] when both the method arg disable and the new attribute are True.

Related Issues

Test Scenarios

Default (disable)

The buttons are disabled (greyed out) after a timeout of 20 seconds.

@slash_command(name="test-x", description="Test command, base case")
async def test_cmd_x(ctx: SlashContext):
  pages = [Embed(f"This is page {i}") for i in range(5)]
  paginator = Paginator.create_from_embeds(bot, *pages, timeout=20)
  await paginator.send(ctx)

Timeout

The buttons are cleared after a timeout of 20 seconds.

@slash_command(name="test-a", description="Test command, scenario A")
async def test_cmd_a(ctx: SlashContext):
  pages = [Embed(f"This is page {i}") for i in range(5)]
  paginator = Paginator.create_from_embeds(bot, *pages, timeout=20)
  paginator.hide_buttons_on_stop = True
  await paginator.send(ctx)

Stop

The buttons are cleared after 8 seconds (due to asyncio.sleep()) since sending.

@slash_command(name="test-b", description="Test command, scenario B")
async def test_cmd_b(ctx: SlashContext):
  pages = [Embed(f"This is page {i}") for i in range(5)]
  paginator = Paginator.create_from_embeds(bot, *pages)
  paginator.hide_buttons_on_stop = True
  await paginator.send(ctx)
  await asyncio.sleep(8)
  await paginator.stop()

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