pagination#

+exception EmptyPaginatorEmbedError[source]#

Bases: Exception

Raised when attempting to paginate with empty contents.

+ +

+class LinePaginator(prefix='```', suffix='```', max_size=4000, scale_to_size=4000, max_lines=None, linesep='\\n')[source]#

Bases: Paginator

A class that aids in paginating code blocks for Discord messages.

Parameters:

pagination_emojis (PaginationEmojis) – The emojis used to navigate pages.
prefix (str) – The prefix inserted to every page. e.g. three backticks.
suffix (str) – The suffix appended at the end of every page. e.g. three backticks.
max_size (int) – The maximum amount of codepoints allowed in a page.
scale_to_size (int) – The maximum amount of characters a single line can scale up to.
max_lines (int) – The maximum amount of lines allowed in a page.

+__init__(prefix='```', suffix='```', max_size=4000, scale_to_size=4000, max_lines=None, linesep='\\n')[source]#

This function overrides the Paginator.__init__ from inside discord.ext.commands.

It overrides in order to allow us to configure the maximum number of lines per page.

+ +

+add_line(line='', *, empty=False)[source]#

Adds a line to the current page.

If a line on a page exceeds max_size characters, then max_size will go up to +scale_to_size for a single line before creating a new page for the overflow words. If it +is still exceeded, the excess characters are stored and placed on the next pages unti +there are none remaining (by word boundary). The line is truncated if scale_to_size is +still exceeded after attempting to continue onto the next page.

In the case that the page already contains one or more lines and the new lines would cause +max_size to be exceeded, a new page is created. This is done in order to make a best +effort to avoid breaking up single lines across pages, while keeping the total length of the +page at a reasonable size.

This function overrides the Paginator.add_line from inside discord.ext.commands.

It overrides in order to allow us to configure the maximum number of lines per page.

Parameters:

line (str) – The line to add to the paginated content.
empty (bool) – Indicates whether an empty line should be added at the end.

Return type:

None

+ +

+async classmethod paginate(pagination_emojis, lines, ctx, embed, *, prefix='', suffix='', max_lines=None, max_size=500, scale_to_size=4000, empty=True, restrict_to_user=None, timeout=300, footer_text=None, url=None, exception_on_empty_embed=False, reply=False, allowed_roles=None)[source]#

Use a paginator and set of reactions to provide pagination over a set of lines.

The reactions are used to switch page, or to finish with pagination.

When used, this will send a message using ctx.send() and apply a set of reactions to it. These reactions may +be used to change page, or to remove pagination from the message.

Pagination will also be removed automatically if no reaction is added for five minutes (300 seconds).

The interaction will be limited to restrict_to_user (ctx.author by default) or +to any user with a moderation role.

Parameters:

pagination_emojis (PaginationEmojis) – The emojis used to navigate pages.
lines (list[str]) – A list of lines to be added to the paginated content.
ctx (discord.ext.commands.Context) – The context in which the pagination is needed.
embed (discord.Embed) – The embed that holds the content, it serves as the page.
prefix (str) – The prefix inserted to every page. e.g. three backticks.
suffix (str) – The suffix appended at the end of every page. e.g. three backticks.
max_lines (int) – The maximum amount of lines allowed in a page.
max_size (int) – The maximum amount of codepoints allowed in a page.
scale_to_size (int) – The maximum amount of characters a single line can scale up to.
empty (bool) – Indicates whether an empty line should be added to each provided line.
restrict_to_user (discord.User) – The user to whom interaction with the pages should be restricted.
timeout (int) – The timeout after which users cannot change pages anymore.
footer_text (str) – Text to be added as a footer for each page.
url (str) – The url to be set for the pagination embed.
exception_on_empty_embed (bool) – Indicates whether to raise an exception when no lines are provided.
reply (bool) – Indicates whether to send the page as a reply to the context’s message.
allowed_roles (Sequence[int]) – A list of role ids that are allowed to change pages.

Return type:

Message | None

Example: +>>> embed = discord.Embed() +>>> embed.set_author(name=”Some Operation”, url=url, icon_url=icon) +>>> await LinePaginator.paginate(pagination_emojis, [line for line in lines], ctx, embed)

+ +

+class PaginationEmojis(**data)[source]#

Bases: BaseModel

The emojis that will be used for pagination.

+model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}#: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.
+

+ +

+model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
+

+ +

+model_fields: ClassVar[dict[str, FieldInfo]] = {'delete': FieldInfo(annotation=str, required=False, default='<:trashcan:637136429717389331>'), 'first': FieldInfo(annotation=str, required=False, default='⏮'), 'last': FieldInfo(annotation=str, required=False, default='⏭'), 'left': FieldInfo(annotation=str, required=False, default='⬅'), 'right': FieldInfo(annotation=str, required=False, default='➡')}#

Metadata about the fields defined on the model, +mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

+ +