Modal API Reference#

class miru.modal.Modal(title: str, *, custom_id: t.Optional[str] = None, timeout: t.Optional[t.Union[float, int, datetime.timedelta]] = 300.0)[source]#

Bases: ItemHandler[ModalActionRowBuilder, ModalContext, ModalItem]

Represents a Discord Modal.

Parameters:

title (str) – The title of the modal, appears on the top of the modal dialog box.
custom_id (str) – The custom identifier of the modal, identifies the modal through interactions.
timeout (Optional[Union[float, int, datetime.timedelta]], optional) – The duration after which the modal times out, in seconds, by default 300.0

Raises:

HandlerFullError – Raised if the modal has more than 25 components attached.
BootstrapFailureError – Raised if miru.install() was never called before instantiation.

add_item(item: ModalItem) → te.Self[source]#

Adds a new item to the modal.

Parameters:

item (ModalItem) – An instance of ModalItem to be added.

Raises:

TypeError – item is not of type ModalItem.
ValueError – The modal already has 25 components attached.
TypeError – Parameter item is not an instance of ModalItem.
RuntimeError – The item is already attached to this view.
RuntimeError – The item is already attached to another view.

Returns:

The item handler the item was added to.

Return type:

ItemHandler

async callback(context: ModalContextT) → None[source]#

Called when the modal is submitted.

Parameters:: context (ModalContext) – The context that belongs to this interaction callback.

get_context(interaction: ~hikari.interactions.modal_interactions.ModalInteraction, values: ~typing.Mapping[~miru.abc.item.ModalItem, str], *, cls: ~typing.Type[~miru.context.modal.ModalContext] = <class 'miru.context.modal.ModalContext'>) → ModalContext[source]#

Get the context for this modal. Override this function to provide a custom context object.

Parameters:

interaction (hikari.ModalInteraction) – The interaction to construct the context from.
cls (Optional[Type[ModalContext]], optional) – The class to use for the context, by default ModalContext.
values (Mapping[ModalItem, str]) – The values received by this modal, mapped to the items they belong to.

Returns:

The context for this interaction.

Return type:

ModalContext

async modal_check(context: ModalContextT) → bool[source]#

Called before any callback in the modal is called. Must evaluate to a truthy value to pass. Override for custom check logic.

Parameters:: context (Context) – The context for this check.
Returns:: A boolean indicating if the check passed or not.
Return type:: bool

async on_error(error: Exception, context: ModalContextT | None = None) → None[source]#

Called when an error occurs in a callback function. Override for custom error-handling logic.

Parameters:

error (Exception) – The exception encountered.
item (Optional[Item[ModalT]], optional) – The item this exception originates from, if any.
context (Optional[Context], optional) – The context associated with this exception, if any.

async send(interaction: ModalResponseMixin) → None[source]#: Send this modal as a response to the provided interaction.

async start() → None[source]#: Start up the modal and begin listening for interactions. This should not be called manually, use Modal.send() or Context.respond_with_modal() instead.

property custom_id: str#: The custom identifier of this modal. Interactions belonging to it are tracked by this ID.

property title: str#: The title of this modal. Will be displayed on the top of the modal prompt.

property values: Mapping[ModalItem, str] | None#: The input values received by this modal.