DiscordUtils.paginator

Module Contents

Classes

RoboPages

Represents a UI view.

FieldPageSource

A page source that requires (field_name, field_value) tuple items.

TextPageSource

A data source for a sequence of items.

SimplePageSource

A data source for a sequence of items.

SimplePages

A simple pagination session reminiscent of the old Pages interface.

EmbedPageSource

A data source for a sequence of items.

EmbedPaginator

A simple paginator for the embeds. In entries you provides a list of embeds
class DiscordUtils.paginator.RoboPages(source, *, ctx, check_embeds=True, compact=False)[source]

Bases: discord.ui.View

Represents a UI view.

This object must be inherited to create a UI within Discord.

New in version 2.0.

Parameters

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the UI before no longer accepting input. If None then there is no timeout.

  • source (menus.PageSource) –

  • ctx (commands.Context) –

  • check_embeds (bool) –

  • compact (bool) –

fill_items(self)[source]
Return type

None

await _get_kwargs_from_page(self, page)[source]
Parameters

page (int) –

Return type

Dict[str, Any]

await show_page(self, interaction, page_number)[source]
Parameters

  • interaction (discord.interactions.Interaction) –

  • page_number (int) –

Return type

None

_update_labels(self, page_number)[source]
Parameters

page_number (int) –

Return type

None

await show_checked_page(self, interaction, page_number)[source]
Parameters

  • interaction (discord.interactions.Interaction) –

  • page_number (int) –

Return type

None

await interaction_check(self, interaction)[source]

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

Note

If an exception occurs within the body then the check is considered a failure and on_error() is called.

Parameters

interaction (Interaction) – The interaction that occurred.

Returns

Whether the view children’s callbacks should be called.

Return type

bool

await on_timeout(self)[source]

This function is a coroutine.

A callback that is called when a view’s timeout elapses without being explicitly stopped.

Return type

None

staticmethod await on_error(error, item, interaction)[source]

This function is a coroutine.

A callback that is called when an item’s callback or interaction_check() fails with an error.

The default implementation logs to the library logger.

Parameters

  • interaction (Interaction) – The interaction that led to the failure.

  • error (Exception) – The exception that was raised.

  • item (Item) – The item that failed the dispatch.

Return type

None

await start(self)[source]
Return type

None

await go_to_first_page(self, button, interaction)[source]

Go to the first page

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

await go_to_previous_page(self, button, interaction)[source]

Go to the previous page

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

await go_to_current_page(self, button, interaction)[source]

As the name suggests, goes to the current page

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

await go_to_next_page(self, button, interaction)[source]

Go to the next page

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

await go_to_last_page(self, button, interaction)[source]

Go to the last page

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

await numbered_page(self, button, interaction)[source]

lets you type a page number to go to

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

await stop_pages(self, button, interaction)[source]

stops the pagination session.

Parameters

  • button (discord.ui.button.Button) –

  • interaction (discord.interactions.Interaction) –

class DiscordUtils.paginator.FieldPageSource(entries, *, per_page=12)[source]

Bases: discord.ext.menus.ListPageSource

A page source that requires (field_name, field_value) tuple items.

await format_page(self, menu, entries)[source]

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a dict then it is interpreted as the keyword-arguments that are used in both discord.Message.edit() and discord.abc.Messageable.send(). The two of interest are embed and content.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

class DiscordUtils.paginator.TextPageSource(text, *, prefix='```', suffix='```', max_size=2000)[source]

Bases: discord.ext.menus.ListPageSource

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries

The sequence of items to paginate.

Type

Sequence[Any]

per_page

How many elements are in a page.

Type

int

await format_page(self, menu, content)[source]

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a dict then it is interpreted as the keyword-arguments that are used in both discord.Message.edit() and discord.abc.Messageable.send(). The two of interest are embed and content.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

staticmethod is_paginating()[source]

This forces the buttons to appear even in the front page

Return type

bool

class DiscordUtils.paginator.SimplePageSource(entries, *, per_page)[source]

Bases: discord.ext.menus.ListPageSource

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries

The sequence of items to paginate.

Type

Sequence[Any]

per_page

How many elements are in a page.

Type

int

await format_page(self, menu, entries)[source]

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a dict then it is interpreted as the keyword-arguments that are used in both discord.Message.edit() and discord.abc.Messageable.send(). The two of interest are embed and content.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

class DiscordUtils.paginator.SimplePages(entries, *, ctx, per_page=12)[source]

Bases: RoboPages

A simple pagination session reminiscent of the old Pages interface. Basically an embed with some normal formatting.

Parameters

  • ctx (commands.Context) –

  • per_page (int) –

class DiscordUtils.paginator.EmbedPageSource(entries, *, per_page)[source]

Bases: discord.ext.menus.ListPageSource

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries

The sequence of items to paginate.

Type

Sequence[Any]

per_page

How many elements are in a page.

Type

int

staticmethod await format_page(menu, entries)[source]

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a discord.Embed then it is interpreted as returning the embed keyword argument in discord.Message.edit() and discord.abc.Messageable.send().

If this method returns a dict then it is interpreted as the keyword-arguments that are used in both discord.Message.edit() and discord.abc.Messageable.send(). The two of interest are embed and content.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Any) – The page returned by PageSource.get_page().

Returns

See above.

Return type

Union[str, discord.Embed, dict]

class DiscordUtils.paginator.EmbedPaginator(entries, *, ctx)[source]

Bases: RoboPages

A simple paginator for the embeds. In entries you provides a list of embeds

Parameters

ctx (commands.Context) –

staticmethod is_paginating()[source]

The pagination is in the paginating state or not. This forces the buttons to appear even in the front page

Returns

bool

Return type

bool