View

Mainly based around the discord.ui.View classes and helpers.

Type of Views

ViewAuthor

class starlight.ViewAuthor(*, delete_after=False, **kwargs)

Bases: View

Implementation of View that has an associated owner and handles message sending.

Parameters:: delete_after (bool) – Indicate whether to delete the message after it has been stopped or timeout. Defaults to False.

async interaction_check(interaction, /)

Implements a check whenever interaction is dispatched onto the View.

Parameters:: interaction (discord.Interaction) – Interaction that triggered the view.
Raises:: NotViewOwner – Triggered when the interaction is unauthorized. This is redirected to ViewAuthor.on_error().
Returns:: The boolean to allow the interaction to invoke the item callback.
Return type:: bool

async on_error(interaction, error, item, /)

Implementation of on_error if an error occurred during the interaction.

Parameters:

interaction (discord.Interaction) – Interaction that triggered the view.
error (Exception) – Error that occurred.
item (discord.ui.Item) – The item that is associated during the error occurrance.

async on_stop(): Implements after processing when the view was stopped or on_timeout triggers.

async on_timeout(): Implementation for on_timeout that implements after processing calling on_stop.

async start(context, *args, **kwargs)

Starts the view by sending a message

This should assign the message that was sent with the view.

Parameters:: context (Context) – The context that will be used to send a message.

stop(*, on_stop=True)

Implementation of stop method.

Parameters:: on_stop (bool) – Whether to trigger on_stop method for after processing. Defaults to True

SimplePaginationView

class starlight.SimplePaginationView(data_source, /, *, cache_page=False, **kwargs)

Bases: ViewAuthor

Implementation View pagination that is written purely without any external library.

This is a simple pagination view without chunking. Chunking of your data should be done before passing into this view.

Parameters:

data_source (List[T]) – The data source that was paginated before hand.
delete_after (bool) – Indicate whether to delete the message after it has been stopped or timeout. Defaults to False.
cache_page (bool) – Indicate whether to cache the result of format_page for better performance. Defaults to False.

context

The context that is associated with this pagination view.

Type:: Optional[Context]

message

The initial message that was sent to the user to be overwritten every interaction.

Type:: Optional[discord.Message]

async change_page(interaction, page)

Implementation to change the page of the View pagination.

Parameters:

interaction (discord.Interaction) – The interaction that is changing the page.
page (int) – The page that the View will switch to.

async change_source(data_source, *, interaction=None, page=0)

Change the source of the pagination view. This will edit the view simultaneously.

Parameters:

data_source (List[T]) – The data source that will be set to the view.
interaction (Optional[discord.Interaction]) – The interaction that is involved on changing the source. It uses discord.Message.edit() if interaction is not provided.
page (int) – The page that will set the paginator to. Defaults to 0.

property current_page: The current page of the pagination view.

property data_source: The data source that is given by the user.

disable_buttons_checker(): Implementation to disable the buttons every page change.

async end_button(interaction, button): Implementation for the end button that set the page to the end of the page.

async format_page(interaction, data)

Implementation for each page should be written in this method.

Parameters:

interaction (Optional[discord.Interaction]) – The interaction associated with the view. Can be None when context.interaction is None during the initial message send.
data (T) – The data that will be on each page. This type is based on data_source.

Returns:

The object that will displayed onto the Message. Returning a dictionary is a keyword arguments for the discord.Message.edit(). By default this returns the str of data argument.

Return type:

Union[Embed, Dict[str, Any], str]

async format_view(interaction, data)

View manipulation should be made on this callback. This is called after format_page finishes invoking.

Parameters:

interaction (Optional[discord.Interaction]) – The interaction associated with the view. Can be None when context.interaction is None during the initial message send.
data (T) – The data that will be on each page. This type is based on data_source.

classmethod from_paginator(paginator, **kwargs)

Classmethod to construct pagination view with Paginator.

paginator = commands.Paginator()
paginator.add_line("Page 1\n Hello!")
paginator.close_page()
paginator.add_line("Page 2\n World!")
paginator.close_page()
view = starlight.SimplePaginationView.from_paginator(paginator)
await view.start(ctx)

This are constructed normally.

Parameters:

paginator (Paginator) – The paginator that will be used.
kwargs (Any) – Key arguments that will be passed to SimplePaginationView.

Returns:

The view paginator constructed.

Return type:

SimplePaginationView

property max_pages: The maximum page of the pagination view that was given.

async next_button(interaction, button): Implementation for the next button that change the page to the next page.

async previous_button(interaction, button): Implementation for the previous button that change the page to the previous page.

async resolved_message_kwargs(interaction, data)

This method handles the cache_page implementation.

Parameters:

interaction (Optional[discord.Interaction]) – The interaction associated with the view interaction.
data (T) – The data that will be on each page. This type is based on data_source.

Returns:

The kwargs that can be provided on discord.Message.edit(). This does not provide you the view key argument.

Return type:

Optional[Dict[str, Any]]

async show_page(interaction, page)

Calls the SimplePaginationView.format_page().

Parameters:

interaction (Optional[discord.Interaction]) – The interaction that will be provided to format_page method.
page (int) – The page that the format_page will set to.

Returns:

Mapping of kwargs that should be given to the discord.Message.edit().

Return type:

Optional[Dict[str, Any]]

async start(context, *, wait=False, message=None)

Initiate the pagination view by sending the message or editing the message when Message is present.

Parameters:

context (Context) – The context associated with the interaction.
wait (bool) – Indicates whether to wait until the pagination finishes. Default to False.
message (Optional[Message]) – If there is already an initial message. Defaults to None.

Returns:

The signature for the command.

Return type:

str

async start_button(interaction, button): Implementation for the start button that sets the page to the first page.

async stop_button(interaction, button): Implementation for the stop button that stops the view.

async to_end(interaction)

Implementation to set the view the end of page.

Parameters:: interaction (discord.Interaction) – The interaction that is changing the page.

async to_next(interaction)

Implementation to change the page to the next page.

Parameters:: interaction (discord.Interaction) – The interaction that is changing the page.

async to_previous(interaction)

Implementation to change the page to the previous page.

Parameters:: interaction (discord.Interaction) – The interaction that is changing the page.

async to_start(interaction)

Implementation to change the page to the start of the page.

Parameters:: interaction (discord.Interaction) – The interaction that is changing the page.

async to_stop(interaction)

Implementation to stop the view.

Parameters:: interaction (discord.Interaction) – The interaction that is stopping the view.

Helpers

InlineView

class starlight.InlineView(view, *, item=None)

Bases: InlineIterator[Tuple[Interaction, Item]]

Implementation of Inline View concepts.

Parameters:

view (discord.ui.View) – The view that will be converted into inline view.
item (Optional[discord.ui.Item]) – The item that should be listen for.

stop(): Implementation of stop. This is automatically called once the view was stopped or timeout.

InlinePagination

class starlight.InlinePagination(pagination_view, context)

Bases: InlineIterator[InlinePaginationItem]

Async iterator that implements inline pagination view.

Parameters:

pagination_view (SimplePaginationView) – The pagination view that will be overwritten.
context (Context) – The context object that will be used to send and manipulate the message.

stop(): Stops the inline pagination iterator. This will also stop the InlinePagination.pagination_view.

InlinePaginationItem

class starlight.InlinePaginationItem(interaction, data)

Implementation for inline pagination item.

This is automatically created by InlinePagination. User should not create this.

Parameters:

interaction (discord.Interaction) – Interaction that invoked the format_page.
data (Chunk) – Data chunks that should be displayed onto the user. The type is depended on data_source.

format(**kwargs)

A method that signals the paginator on what format should the message show to the user.

Parameters:: kwargs (Any) – Key arguments that will be given to discord.Message.edit(). Not passing anything will ignore the sequence.

async wait()

Waits for the result to be set on the item.

Returns:

Dict[str, Any]
The mapping that was set by the InlinePaginationItem.format().