Skip to main content

Unofficial discord-interactions multi page embed handler

Project description

dinteractions-Paginator

Unofficial discord-interactions multi-page embed handler

Discord PyPI - Downloads

Table of Contents

(Only works in the GitHub for some reason)

Features

  • Message per embed or persistent message
  • Index select that can be turned on/off
  • Select labels are generated based on embed's title
  • Index button that can be turned on/off
  • Ability to set the buttons to any emote, color or label
  • Custom buttons

Join our Discord server!

  • Try out all the possible combinations of the paginator with /example1 and /example2,
  • Ask some questions,
  • And give us feedback and suggestions!

Wanna contribute?

  • Make an issue to:
    • say what feature you want to be added
    • file a bug report
  • Make a pull request and:
    • describe what you added/removed
    • why you added/removed it
  • Make sure you use the issue/PR template!

Installation

pip install -U dinteractions-Paginator

Dependencies

Examples:

These simple examples show how to easily create interactive, multiple page embeds that anyone can interact with that automatically deactivate after 60 seconds of inactivity:

Example GIF:

Paginator with select:

Slash command:

import discord
from discord.ext import commands
from discord_slash import SlashCommand, SlashContext
from dinteractions_Paginator import Paginator

bot = commands.Bot(command_prefix="/")
slash = SlashCommand(bot, sync_commands=True)


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}!")


@slash.slash(name="embeds")
async def embeds(ctx: SlashContext):
    one = discord.Embed(title="1st Embed", description="General Kenobi!", color=discord.Color.red())
    two = discord.Embed(title="2nd Embed", description="General Kenobi!", color=discord.Color.orange())
    three = discord.Embed(title="3rd Embed", description="General Kenobi!", color=discord.Color.gold())
    four = discord.Embed(title="4th Embed", description="General Kenobi!", color=discord.Color.green())
    five = discord.Embed(title="5th Embed", description="General Kenobi!", color=discord.Color.blue())
    pages = [one, two, three, four, five]

    await Paginator(bot=bot, ctx=ctx, pages=pages, content=["1", "2", "3", "4", "5"], timeout=60).run()


bot.run("token")

Normal command:

import discord
from discord.ext import commands
from discord_slash import SlashCommand
from dinteractions_Paginator import Paginator

bot = commands.Bot(command_prefix="/")
slash = SlashCommand(bot)


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}!")


@bot.command()
async def embeds(ctx):
    one = discord.Embed(title="1st Embed", description="General Kenobi!", color=discord.Color.red())
    two = discord.Embed(title="2nd Embed", description="General Kenobi!", color=discord.Color.orange())
    three = discord.Embed(title="3rd Embed", description="General Kenobi!", color=discord.Color.gold())
    four = discord.Embed(title="4th Embed", description="General Kenobi!", color=discord.Color.green())
    five = discord.Embed(title="5th Embed", description="General Kenobi!", color=discord.Color.blue())
    pages = [one, two, three, four, five]

    await Paginator(bot=bot, ctx=ctx, pages=pages, content=["1", "2", "3", "4", "5"], timeout=60).run()


bot.run("token")

NOTE: slash = SlashCommand(bot) required to override bot

class Paginator

Arguments

Required:

  • bot - commands.Bot: The bot variable, commands.Bot is required
  • ctx
    • Union[SlashContext, commands.Context, ComponentContext, MenuContext, discord.channel.TextChannel, discord.User, discord.Member]: The context of a command.
      NOTE: if one of the latter 3 are used, there will always be a This interaction failed even though it was a success, due to no context to respond to

Optional:

  • pages - Optional[List[discord.Embed]]: the list of embeds to be paginated, defaults to None and paginates content instead
    NOTE: content must be a list for paginating without pages!
  • content - Optional[Union[str, List[str]]]: the content of the message to send, defaults to None
  • files - Optional[Union[discord.File, List[discord.File]]]: files to send, defaults to None
  • hidden - Optional[bool]: if you want the paginator to be hidden, default False
  • authorOnly - Optional[bool]: if you want the paginator to work for the author only, default is False
  • onlyFor - Optional[Union[discord.User, discord.Role, List[Union[discord.User, discord.Role]]]]: components only for specified user(s) or role(s)
  • dm - Optional[bool]: if you want the paginator to be DM'ed, default False
  • customActionRow - Optional[List[Union[dict, Callable]]]: a custom action row, see this for more info, defaults to None

Time:

  • timeout - Optional[int]: deactivates paginator after inactivity if enabled, defaults to None (meaning no timeout)
  • disableAfterTimeout - Optional[bool]: disable components after timeout, default True
  • deleteAfterTimeout - Opti onal[bool]: delete components after timeout, default False

What to use:

  • useButtons - Optional[bool]: uses buttons, default is True
  • useSelect - Optional[bool]: uses a select, default is True
  • useIndexButton - Optional[bool]: uses the index button, default is False and stays False if useButtons is also False
  • useLinkButton - Optional[bool]: uses the link button
  • useQuitButton - Optional[bool]: quit button to end the paginator, default False
  • useFirstLast - Optional[bool]: uses the first and last buttons, default True
  • useOverflow - Optional[bool]: uses the overflow action row if there are too many buttons, default True
  • useNotYours - Optional[bool]: sends an ephemeral (hidden) message if the paginator is not yours (see authorOnly or onlyFor), default True

Labels:

  • firstLabel - Optional[str]: The label of the button used to go to the first page, defaults to ""
  • prevLabel - Optional[str]: The label of the button used to go to the previous page, defaults to ""
  • indexLabel - Optional[str]: The label of the index button, defaults to "Page"
  • nextLabel - Optional[str]: The label of the button used to go to the next page, defaults to ""
  • lastLabel - Optional[str]: The label of the button used to go to the last page, defaults to ""
  • linkLabel - Optional[Union[str, List[str]]]: The label for the link button
  • linkURL - Optional[Union[str, List[str]]]: The URL(s) for the link button
  • customButtonLabel - Optional[str]: The label of a custom disabled button, default None
  • quitButtonLabel - Optional[str]: The label of the quit button, default "Quit"

Emojis:

  • firstEmoji - Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]: emoji of the button used to go to the first page, defaults to "⏮️"
  • prevEmoji - Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]: emoji of the button used to go to the previous page, defaults to "◀"
  • nextEmoji - Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]: emoji of the button used to go to the next page, defaults to "▶"
  • lastEmoji - Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]: emoji of the button used to go to the last page, defaults to "⏭️"
  • customButtonEmoji - Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]: emoji of the custom disabled button, defaults to None
  • quitButtonEmoji - Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]: emoji of the quit button, defaults to None

Styles (the colo[u]r of the buttons):

  • firstStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the first button, defaults to 1 (ButtonStyle.blue)
  • prevStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the previous button, defaults to 1 (ButtonStyle.blue)
  • indexStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the index button, defaults to 3 (ButtonStyle.green)
  • nextStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the next button, defaults to 1 (ButtonStyle.blue)
  • lastStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the last button, defaults to 1 (ButtonStyle.blue)
  • customButtonStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the custom disabled button, defaults to 2 (ButtonStyle.gray)
  • quitButtonStyle - Optional[Union[ButtonStyle, int]]: the style of button (ButtonStyle or int) for the quit button, defaults to 4 (ButtonStyle.red)

Returns

class TimedOut

More info on customActionRow:

You can define your own custom action row, with its own code!

Example code:

@slash.slash(name="custom-action-row")
async def _custom_action_row(ctx: SlashContext):
    # Embeds:
    pages = [
        discord.Embed(title="1"),
        discord.Embed(title="2"),
        discord.Embed(title="3"),
        discord.Embed(title="4"),
        discord.Embed(title="5"),
    ]

    # Action row:
    buttons = [
        create_button(style=3, label="A Green Button"),
    ]
    custom_action_row = create_actionrow(*buttons)

    # Function:
    async def custom_function(self, button_ctx):
        await button_ctx.send("test", hidden=True)
        await self.ctx.send("lol")

    # Paginator:
    await Paginator(
        bot,
        ctx,
        pages,
        timeout=60,
        customActionRow=[
            custom_action_row,
            custom_function,
        ],  # Note that custom_function is not called
    ).run()

The code above runs a normal paginator, with 1 extra action row at the bottom!

Example GIF:

You can access all of the attributes of class Paginator with self, such as the original command's context (self.ctx), the bot variable (self.bot), and other things that you passed into it!

Template:

# <-- Your decorator here
# ...
buttons = [
    create_button(style=3, label="A Green Button"),
    ...  # Your buttons
]
custom_action_row = create_actionrow(*buttons)


# Function:
async def custom_function(self, button_ctx):
    pass  # Your code for the action row here
    # You could check for each button and decide
    # what to do


await Paginator(..., customActionRow=[custom_action_row, custom_function]).run()

class TimedOut

Attributes

  • ctx - Union[commands.Context, SlashContext]: The original context
  • buttonContext - ComponentContext: The context for the paginator's components
  • timeTaken - int: How long in seconds that user(s) used the paginator before the timeout
  • lastContent - str: The last content that the paginator stopped at after timeout
  • lastEmbed - discord.Embed: The last embed that the paginator stopped at after timeout
  • successfulUsers - List[discord.User]: Users that successfully used the paginator, the first user is the invoker
  • failedUsers - List[discord.User]: Users that failed to use the paginator

Credits

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dinteractions_Paginator-1.3.6.tar.gz (26.6 kB view details)

Uploaded Source

Built Distribution

dinteractions_Paginator-1.3.6-py3-none-any.whl (23.6 kB view details)

Uploaded Python 3

File details

Details for the file dinteractions_Paginator-1.3.6.tar.gz.

File metadata

  • Download URL: dinteractions_Paginator-1.3.6.tar.gz
  • Upload date:
  • Size: 26.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.2 CPython/3.9.7

File hashes

Hashes for dinteractions_Paginator-1.3.6.tar.gz
Algorithm Hash digest
SHA256 85bb9092dba0bf6c2dbfe09274406d08d82a4e21252aa71f664d3083369c7a1e
MD5 80d807a92a20efcd380e7bfb6a0197a1
BLAKE2b-256 df70ebd36b54f9c0a5f2d580be6d7405bf7a494bef16d03bd301f9714630f377

See more details on using hashes here.

File details

Details for the file dinteractions_Paginator-1.3.6-py3-none-any.whl.

File metadata

  • Download URL: dinteractions_Paginator-1.3.6-py3-none-any.whl
  • Upload date:
  • Size: 23.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.2 CPython/3.9.7

File hashes

Hashes for dinteractions_Paginator-1.3.6-py3-none-any.whl
Algorithm Hash digest
SHA256 f6203c53dee1fd9bb944e662dda6123c871441ef2edd4d74ecc16e0ac4215e7e
MD5 6933bc38c2c4735c5f89188fbdf5b728
BLAKE2b-256 f353ad07434e5c52628163371688a40b03f1839517f0eef7ddbffb32729ffb79

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page