Module Reference

Module reference for discord.ext.paginator

Paginators

Paginator

class discord.ext.paginator.Paginator(view: Type[discord.ext.paginator.paginator.DefaultView], *, pages: List[Dict[str, Any]] = [], embeds: List[Union[discord.embeds.Embed, List[discord.embeds.Embed]]] = [], messages: List[str] = [], cyclical: bool = True, allow_fast_traverse: bool = False, current_page: int = 0, start_page: int = 0, timeout: Optional[int] = 180, author_only: bool = True, edit: bool = True)

Base class for defining paginators

Parameters

• view (Type[ModifiedView]) – View instance which handles editing messages, for built-in paginators such as ButtonsPaginator, this arg is invalid.

• pages (List[Dict[str, Any]]) –

  An array of pages, i.e messages to send as page.

  Note

  This MUST be a dictionary

  diff

    # Page content is sent using kwargs
    # Where page = pages[page_index]
  + Context.send(**page)
  

• embeds (List[Union[Embed, List[Embed]]]) – An array of embeds or a 2d array of embeds to send as pages, if pages are provided then these are appended to these values.

• messages (List[str]) – An array of message contents to send as pages, if pages are provided this overwrite previous content

• cyclical (bool) – Whether you can traverse from start to end and vise versa once limit reached, if not end/start page are continually returned

• allow_fast_traverse (bool) – Whether to allow direct traversing from start to end and vise versa

• current_page (int) – Index of page paginator starts on, uses zero indexing

• start_page (int) – Index of starting page for paginator, to use this value instead of current page, set current page to an invalid value e.g. -1. This is also used when traversing to start directly.

• timeout (int) – Timeout for paginator view, defaults to 180

• author_only (bool) – Whether only the person who invoked the pagination is only allowed to respond

• edit (bool) – Whether to edit existing view message or generate a new one.

async end() → None

Ends pagination

async on_end()

An event called when pagination ends, directly before message is sent

async on_start()

An event called when pagination starts, directly before message is sent

async on_traverse_back()

An event called right before backward traversed page is returned

async on_traverse_end()

An event called right before moving to Paginator.max_page

async on_traverse_forward()

An event called right before forward traversed page is returned

async on_traverse_start()

An event called right before moving to Paginator.start_page

async on_traverse_to()

An event called before a page is traversed to using Paginator.traverse_to()

async start(ctx: Union[discord.ext.commands.context.Context, discord.interactions.Interaction], *, timeout: int = Ellipsis, call: Optional[Callable[[...], Any]] = None) → None

Starts pagination

Parameters

• ctx (Context) – Context to pass to view

• timeout (Optional[int]) – Default timeout

• call (Callable[..., Any]) –

  Function to call rather then ctx.send()

  Example

  py

  await Paginator.context_start(Context, call=Context.reply)
  

async traverse_back() → Dict[str, Any]

Moves backward, i.e previous page

async traverse_end() → Dict[str, Any]

Moves to the end, Paginator.max_page

async traverse_forward() → Dict[str, Any]

Moves forward, i.e. next page

async traverse_start() → Dict[str, Any]

Moves to the start, Paginator.start_page

async traverse_to(page: int) → Dict[str, Any]

Moves to a specific page

Parameters

page (int) – Page to traverse to

ButtonPaginator

class discord.ext.paginator.ButtonPaginator(*, traverse_start_button: discord.ui.button.Button = <Button style=<ButtonStyle.primary: 1> url=None disabled=False label=None emoji=<PartialEmoji animated=False name='⏪' id=None> row=1>, traverse_back_button: discord.ui.button.Button = <Button style=<ButtonStyle.primary: 1> url=None disabled=False label=None emoji=<PartialEmoji animated=False name='◀️' id=None> row=1>, traverse_stop_button: discord.ui.button.Button = <Button style=<ButtonStyle.primary: 1> url=None disabled=False label=None emoji=<PartialEmoji animated=False name='⏹️' id=None> row=1>, traverse_forward_button: discord.ui.button.Button = <Button style=<ButtonStyle.primary: 1> url=None disabled=False label=None emoji=<PartialEmoji animated=False name='▶️' id=None> row=1>, traverse_end_button: discord.ui.button.Button = <Button style=<ButtonStyle.primary: 1> url=None disabled=False label=None emoji=<PartialEmoji animated=False name='⏩' id=None> row=1>, extras: List[Union[List[discord.ui.item.Item], discord.ui.item.Item]] = [], **paginator_kwds)

Default implementation for button pagination

Note

All parameters apart from view from Paginator are valid.

Parameters

• traverse_start_button (Button) – Custom start button, callback will be overwritten

• traverse_back_button (Button) – Custom back button, callback will be overwritten

• traverse_stop_button (Button) – Custom stop button, callback will be overwritten

• traverse_forward_button (Button) – Custom forward button, callback will be overwritten

• traverse_end_button (Button) – Custom end button, callback will be overwritten

• extras (List[Union[List[Item], Item]]) – Extra components to add to paginator

async end() → None

Ends pagination

async on_end()

An event called when pagination ends, directly before message is sent

async on_start()

An event called when pagination starts, directly before message is sent

async on_traverse_back()

An event called right before backward traversed page is returned

async on_traverse_end()

An event called right before moving to Paginator.max_page

async on_traverse_forward()

An event called right before forward traversed page is returned

async on_traverse_start()

An event called right before moving to Paginator.start_page

async on_traverse_to()

An event called before a page is traversed to using Paginator.traverse_to()

async start(ctx: Union[discord.ext.commands.context.Context, discord.interactions.Interaction], *, timeout: int = Ellipsis, call: Optional[Callable[[...], Any]] = None) → None

Starts pagination

Parameters

• ctx (Context) – Context to pass to view

• timeout (Optional[int]) – Default timeout

• call (Callable[..., Any]) –

  Function to call rather then ctx.send()

  Example

  py

  await Paginator.context_start(Context, call=Context.reply)
  

async traverse_back() → Dict[str, Any]

Moves backward, i.e previous page

async traverse_end() → Dict[str, Any]

Moves to the end, Paginator.max_page

async traverse_forward() → Dict[str, Any]

Moves forward, i.e. next page

async traverse_start() → Dict[str, Any]

Moves to the start, Paginator.start_page

async traverse_to(page: int) → Dict[str, Any]

Moves to a specific page

Parameters

page (int) – Page to traverse to

DropdownPaginator

class discord.ext.paginator.DropdownPaginator(*, placeholer: Union[str, discord.ext.paginator.dropdown_pag.GenPlaceholder] = <discord.ext.paginator.dropdown_pag.GenPlaceholder object>, **paginator_kwds)

Default implementation of a dropdown paginator

Note

All parameters from Paginator are valid except view and allow_fast_traverse

Parameters

placeholder (Union[str, GenPlaceholder]) – Placeholder to display, for dynamically generated placeholders use GenPlaceholder

async end() → None

Ends pagination

async on_end()

An event called when pagination ends, directly before message is sent

async on_start()

An event called when pagination starts, directly before message is sent

async on_traverse_back()

An event called right before backward traversed page is returned

async on_traverse_end()

An event called right before moving to Paginator.max_page

async on_traverse_forward()

An event called right before forward traversed page is returned

async on_traverse_start()

An event called right before moving to Paginator.start_page

async on_traverse_to()

An event called before a page is traversed to using Paginator.traverse_to()

async start(ctx: Union[discord.ext.commands.context.Context, discord.interactions.Interaction], *, timeout: int = Ellipsis, call: Optional[Callable[[...], Any]] = None) → None

Starts pagination

Parameters

• ctx (Context) – Context to pass to view

• timeout (Optional[int]) – Default timeout

• call (Callable[..., Any]) –

  Function to call rather then ctx.send()

  Example

  py

  await Paginator.context_start(Context, call=Context.reply)
  

async traverse_back() → Dict[str, Any]

Moves backward, i.e previous page

async traverse_end() → Dict[str, Any]

Moves to the end, Paginator.max_page

async traverse_forward() → Dict[str, Any]

Moves forward, i.e. next page

async traverse_start() → Dict[str, Any]

Moves to the start, Paginator.start_page

async traverse_to(page: int) → Dict[str, Any]

Moves to a specific page

Parameters

page (int) – Page to traverse to

Views

PaginatorView

class discord.ext.paginator.PaginatorView(*, timeout: Optional[float] = 180.0)

add_item(item: Item[Any]) → Self

Adds an item to the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to add to the view.

Raises

• TypeError – An Item was not passed.

• ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

clear_items() → Self

Removes all items from the view.

This function returns the class instance to allow for fluent-style chaining.

classmethod from_message(message: Message, /, *, timeout: Optional[float] = 180.0) → View

Converts a message’s components into a View.

The Message.components of a message are read-only and separate types from those in the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

Parameters

• message (discord.Message) – The message with components to convert into a view.

• timeout (Optional[float]) – The timeout of the converted view.

Returns

The converted view. This always returns a View and not one of its subclasses.

Return type

View

async interaction_check(interaction: Interaction, /) → bool

|coro|

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

is_dispatching() → bool

bool: Whether the view has been added for dispatching purposes.

is_finished() → bool

bool: Whether the view has finished interacting.

is_persistent() → bool

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

async on_error(interaction: Interaction, error: Exception, item: Item[Any], /) → None

|coro|

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.

async on_timeout() → None

|coro|

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

remove_item(item: Item[Any]) → Self

Removes an item from the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to remove from the view.

stop() → None

Stops listening to interaction events from this view.

This operation cannot be undone.

async wait() → bool

|coro|

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

property children: List[Item[Self]]

The list of children attached to this view.

Type

List[Item]

property timeout: Optional[float]

The timeout in seconds from last interaction with the UI before no longer accepting input. If None then there is no timeout.

Type

Optional[float]

DefaultView

class discord.ext.paginator.DefaultView(ctx: discord.ext.commands.context.Context, paginator: discord.ext.paginator.paginator.Paginator, *, timeout: Optional[float] = 180)

add_item(item: Item[Any]) → Self

Adds an item to the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to add to the view.

Raises

• TypeError – An Item was not passed.

• ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

clear_items() → Self

Removes all items from the view.

This function returns the class instance to allow for fluent-style chaining.

classmethod from_message(message: Message, /, *, timeout: Optional[float] = 180.0) → View

Converts a message’s components into a View.

The Message.components of a message are read-only and separate types from those in the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

Parameters

• message (discord.Message) – The message with components to convert into a view.

• timeout (Optional[float]) – The timeout of the converted view.

Returns

The converted view. This always returns a View and not one of its subclasses.

Return type

View

async interaction_check(interaction: Interaction, /) → bool

|coro|

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

is_dispatching() → bool

bool: Whether the view has been added for dispatching purposes.

is_finished() → bool

bool: Whether the view has finished interacting.

is_persistent() → bool

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

async on_error(interaction: Interaction, error: Exception, item: Item[Any], /) → None

|coro|

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.

async on_timeout() → None

|coro|

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

remove_item(item: Item[Any]) → Self

Removes an item from the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to remove from the view.

stop() → None

Stops listening to interaction events from this view.

This operation cannot be undone.

async wait() → bool

|coro|

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

property children: List[Item[Self]]

The list of children attached to this view.

Type

List[Item]

property timeout: Optional[float]

The timeout in seconds from last interaction with the UI before no longer accepting input. If None then there is no timeout.

Type

Optional[float]

ButtonPaginatorView

class discord.ext.paginator.ButtonPaginatorView(ctx: discord.ext.commands.context.Context, paginator: discord.ext.paginator.button_pag.ButtonPaginator, *, timeout: Optional[float] = 180)

add_item(item: Item[Any]) → Self

Adds an item to the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to add to the view.

Raises

• TypeError – An Item was not passed.

• ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

clear_items() → Self

Removes all items from the view.

This function returns the class instance to allow for fluent-style chaining.

classmethod from_message(message: Message, /, *, timeout: Optional[float] = 180.0) → View

Converts a message’s components into a View.

The Message.components of a message are read-only and separate types from those in the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

Parameters

• message (discord.Message) – The message with components to convert into a view.

• timeout (Optional[float]) – The timeout of the converted view.

Returns

The converted view. This always returns a View and not one of its subclasses.

Return type

View

async interaction_check(interaction: Interaction, /) → bool

|coro|

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

is_dispatching() → bool

bool: Whether the view has been added for dispatching purposes.

is_finished() → bool

bool: Whether the view has finished interacting.

is_persistent() → bool

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

async on_error(interaction: Interaction, error: Exception, item: Item[Any], /) → None

|coro|

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.

async on_timeout() → None

|coro|

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

remove_item(item: Item[Any]) → Self

Removes an item from the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to remove from the view.

stop() → None

Stops listening to interaction events from this view.

This operation cannot be undone.

async wait() → bool

|coro|

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

property children: List[Item[Self]]

The list of children attached to this view.

Type

List[Item]

property timeout: Optional[float]

The timeout in seconds from last interaction with the UI before no longer accepting input. If None then there is no timeout.

Type

Optional[float]

DropdownPaginatorView

class discord.ext.paginator.DropdownPaginatorView(ctx: discord.ext.commands.context.Context, paginator: discord.ext.paginator.dropdown_pag.DropdownPaginator, *, timeout: Optional[float] = 180)

add_item(item: Item[Any]) → Self

Adds an item to the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to add to the view.

Raises

• TypeError – An Item was not passed.

• ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

clear_items() → Self

Removes all items from the view.

This function returns the class instance to allow for fluent-style chaining.

classmethod from_message(message: Message, /, *, timeout: Optional[float] = 180.0) → View

Converts a message’s components into a View.

The Message.components of a message are read-only and separate types from those in the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

Parameters

• message (discord.Message) – The message with components to convert into a view.

• timeout (Optional[float]) – The timeout of the converted view.

Returns

The converted view. This always returns a View and not one of its subclasses.

Return type

View

async interaction_check(interaction: Interaction, /) → bool

|coro|

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

is_dispatching() → bool

bool: Whether the view has been added for dispatching purposes.

is_finished() → bool

bool: Whether the view has finished interacting.

is_persistent() → bool

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

async on_error(interaction: Interaction, error: Exception, item: Item[Any], /) → None

|coro|

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.

async on_timeout() → None

|coro|

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

remove_item(item: Item[Any]) → Self

Removes an item from the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters

item (Item) – The item to remove from the view.

stop() → None

Stops listening to interaction events from this view.

This operation cannot be undone.

async wait() → bool

|coro|

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

property children: List[Item[Self]]

The list of children attached to this view.

Type

List[Item]

property timeout: Optional[float]

The timeout in seconds from last interaction with the UI before no longer accepting input. If None then there is no timeout.

Type

Optional[float]

Others

GenPlaceholder

class discord.ext.paginator.GenPlaceholder

Class used for generating placeholders dynamically between pages,

Example

py

from discord.ext.paginator import GenPlaceholder

class MyPlaceholder(GenPlaceholder):
    def generate(self, paginator):
        return 'Menu Page {current_page} out of {max_page}'.format(
            current_page=paginator.current_page + 1,
            max_page=paginator.max_page + 1
        )