Skip to content

yuyo.modals#

Higher level client for modal execution.

Client module-attribute #

Client = ModalClient

Alias of ModalClient.

Context module-attribute #

Context = ModalContext

Alias of ModalContext.

NO_DEFAULT module-attribute #

NO_DEFAULT = VALUE

Singleton used to signify when a field has no default.

WaitFor module-attribute #

WaitFor = WaitForModal

Alias of WaitForModal.

AbstractModal #

Bases: ABC

Base class for a modal execution handler.

execute abstractmethod async #

execute(ctx)

Execute this modal.

Parameters:

  • ctx (Context) –

    The context to execute this with.

Modal #

Bases: AbstractModal

Standard implementation of a modal executor.

To send this modal pass Modal.rows as components when calling create_modal_response.

Examples:

There's a few different ways this can be used to create a modal.

Sub-components can be added to an instance of a modal using chainable methods:

async def callback(
    ctx: modals.Context, field: str, other_field: str | None
) -> None:
    await ctx.respond("hi")

modal = (
    modals.modal(callback, ephemeral_default=True)
    .add_text_input("Title A", parameter="field")
    .add_text_input(
        "Title B",
        style=hikari.TextInputStyle.PARAGRAPH,
        parameter="other_field",
        default=None,
    )
)

or using decorator methods:

@modals.with_text_input(
    "Title B",
    style=hikari.TextInputStyle.PARAGRAPH,
    parameter="other_field",
    default=None,
)
@modals.with_text_input("Title A", parameter="field")
@modals.as_modal(ephemeral_default=True)
async def callback(
    ctx: modals.Context, field: str, other_field: str | None
) -> None:
    await ctx.respond("bye")

Note

Since decorators are executed from the bottom upwards fields added through decorator calls will follow the same order.

Subclasses of Modal can act as a template where "static" fields are included on all instances and subclasses of that class:

@modals.with_static_text_input(
    "Title B",
    style=hikari.TextInputStyle.PARAGRAPH,
    parameter="other_field",
    default=None,
)
@modals.with_static_text_input("Title A", parameter="field")
class CustomModal(modals.Modal):
    # The init can be overridden to store extra data on the column object when subclassing.
    def __init__(self, special_string: str, ephemeral_default: bool = False):
        super().__init__(ephemeral_default=ephemeral_default)
        self.special_string = special_string

    async def callback(
        ctx: modals.Context,
        field: str,
        other_field: str | None,
        value: str
    ) -> None:
        await ctx.respond("Good job")

Templates can be made by subclassing Modal and defining the method callback for handling context menu execution (this must be valid for the signature signature (modals.Context, ...) -> Coroutine[Any, Any, None]).

@modals.with_static_text_input(
    "Title B",
    style=hikari.TextInputStyle.PARAGRAPH,
    parameter="other_field",
    default=None,
)
@modals.with_static_text_input("Title A", parameter="field")
@modals.as_modal_template
async def custom_modal(
    ctx: modals.Context,
    field: str,
    other_field: str | None,
    value: str,
) -> None:
    await ctx.respond("Bye")

or by using as_modal_template (which returns a class which functions like a Modal subclass) The chainable add_static_{}() classmethods can also be used to add static fields to a Modal subclass.

Modals also support declaring entries using the following parameter descriptors:

class ModalOptions(modals.ModalOptions):
    foo: str = modals.text_input("label")
    bar: str | None = modals.text_unput(
        "label", style=hikari.TextInputStyle.PARAGRAPH, default=None
    )

@yuyo.modals.as_modal_template
async def callback(
    ctx: modals.Context,
    options: ModalOptions,
    field: str = modals.text_input("label", value="yeet")
)

These can either be applied to the default of an argument or defined as an attribute on a ModalOptions subclass ( ModalOptions should then be used as an argument's type-hint). This also works for Modal subclasses which have a Modal.callback method.

rows property #

rows

Builder objects of the rows in this modal.

__init__ #

__init__(*, ephemeral_default=False, id_metadata=None)

Initialise a component executor.

Parameters:

  • ephemeral_default (bool, default: False ) –

    Whether this executor's responses should default to being ephemeral.

  • id_metadata (Union[Mapping[str, str], None], default: None ) –

    Mapping of metadata to append to the custom IDs in this modal.

    The keys should be the match part of field custom IDs.

add_static_text_input classmethod #

add_static_text_input(label, /, *, custom_id=None, style=hikari.TextInputStyle.SHORT, placeholder=hikari.UNDEFINED, value=hikari.UNDEFINED, default=NO_DEFAULT, min_length=0, max_length=4000, parameter=None)

Add a text input field to all instances and subclasses of this modal class.

Parameters:

  • label (str) –

    The text input field's display label.

    This cannot be greater than 45 characters long.

  • custom_id (Optional[str], default: None ) –

    The field's custom ID.

    Defaults to parameter, if provided, or a UUID and cannot be longer than 100 characters.

    Only custom_id.split(":", 1)[0] will be used to match against interactions. Anything after ":" is metadata.

  • style (TextInputStyle, default: SHORT ) –

    The text input's style.

  • placeholder (UndefinedOr[str], default: UNDEFINED ) –

    Placeholder text to display when the text input is empty.

  • value (UndefinedOr[str], default: UNDEFINED ) –

    Default text to pre-fill the field with.

  • default (Any, default: NO_DEFAULT ) –

    Default value to pass if this text input field was not provided.

    The field will be marked as required unless this is supplied.

    This will also be used for value when it has been left undefined and the default is a string that's <=4000 characters in length.

  • min_length (int, default: 0 ) –

    Minimum length the input text can be.

    This can be greater than or equal to 0 and less than or equal to 4000.

  • max_length (int, default: 4000 ) –

    Maximum length the input text can be.

    This can be greater than or equal to 1 and less than or equal to 4000.

  • parameter (Optional[str], default: None ) –

    Name of the parameter the text for this field should be passed to.

    This will be of type str and may also be the value passed for default.

Returns:

  • type[Self] –

    The class to enable call chaining.

Raises:

add_text_input #

add_text_input(label, /, *, custom_id=None, style=hikari.TextInputStyle.SHORT, placeholder=hikari.UNDEFINED, value=hikari.UNDEFINED, default=NO_DEFAULT, min_length=0, max_length=4000, parameter=None)

Add a text input field to this modal instance.

Parameters:

  • label (str) –

    The text input field's display label.

    This cannot be greater than 45 characters long.

  • custom_id (Optional[str], default: None ) –

    The field's custom ID.

    Defaults to parameter, if provided, or a UUID and cannot be longer than 100 characters.

    Only custom_id.split(":", 1)[0] will be used to match against interactions. Anything after ":" is metadata.

  • style (TextInputStyle, default: SHORT ) –

    The text input's style.

  • placeholder (UndefinedOr[str], default: UNDEFINED ) –

    Placeholder text to display when the text input is empty.

  • value (UndefinedOr[str], default: UNDEFINED ) –

    Default text to pre-fill the field with.

  • default (Any, default: NO_DEFAULT ) –

    Default value to pass if this text input field was not provided.

    The field will be marked as required unless this is supplied.

    This will also be used for value when it has been left undefined and the default is a string that's <=4000 characters in length.

  • min_length (int, default: 0 ) –

    Minimum length the input text can be.

    This can be greater than or equal to 0 and less than or equal to 4000.

  • max_length (int, default: 4000 ) –

    Maximum length the input text can be.

    This can be greater than or equal to 1 and less than or equal to 4000.

  • parameter (Optional[str], default: None ) –

    Name of the parameter the text for this field should be passed to.

    This will be of type str and may also be the value passed for default.

Returns:

  • Self –

    The modal instance to enable call chaining.

ModalClient #

Client used to handle modals within a REST or gateway flow.

alluka property #

alluka

The Alluka client being used for callback dependency injection.

cache property #

cache

Hikari cache instance this client was initialised with.

events property #

events

Object of the event manager this client was initialised with.

rest property #

rest

Object of the Hikari REST client this client was initialised with.

server property #

server

Object of the Hikari interaction server provided for this client.

shards property #

shards

Object of the Hikari shard manager this client was initialised with.

voice property #

voice

Object of the Hikari voice component this client was initialised with.

__init__ #

__init__(*, alluka=None, cache=None, event_manager=None, event_managed=None, rest=None, server=None, shards=None, voice=None)

Initialise a modal client.

This registers ModalClient as a type dependency when alluka isn't passed.

Note

For an easier way to initialise the client from a bot see ModalClient.from_gateway_bot, ModalClient.from_rest_bot, and ModalClient.from_tanjun.

Parameters:

  • alluka (Optional[Client], default: None ) –

    The Alluka client to use for callback dependency injection in this client.

    If not provided then this will initialise its own Alluka client.

  • event_manager (Optional[EventManager], default: None ) –

    The event manager this client should listen to dispatched modal interactions from if applicable.

  • event_managed (Optional[bool], default: None ) –

    Whether this client should be automatically opened and closed based on the lifetime events dispatched by event_manager.

    Defaults to True if an event manager is passed.

  • server (Optional[InteractionServer], default: None ) –

    The server this client should listen to modal interactions from if applicable.

Raises:

close #

close()

Close the modal client.

deregister_modal #

deregister_modal(custom_id)

Remove the modal set for a custom ID.

Parameters:

  • custom_id (str) –

    The custom_id to unset the modal for.

Returns:

  • Self –

    The modal client to allow chaining.

Raises:

  • KeyError –

    If the custom_id is not registered.

from_gateway_bot classmethod #

from_gateway_bot(bot, /, *, alluka=None, event_managed=True)

Build a modal client from a Gateway Bot.

This registers ModalClient as a type dependency when alluka isn't passed.

Parameters:

  • bot (_GatewayBotProto) –

    The Gateway bot this modal client should be bound to.

  • alluka (Optional[Client], default: None ) –

    The Alluka client to use for callback dependency injection in this client.

    If not provided then this will initialise its own Alluka client.

  • event_managed (bool, default: True ) –

    Whether the modal client should be automatically opened and closed based on the lifetime events dispatched by bot.

Returns:

from_rest_bot classmethod #

from_rest_bot(bot, /, *, alluka=None, bot_managed=False)

Build a modal client from a REST Bot.

This registers ModalClient as a type dependency when alluka isn't passed.

Parameters:

  • bot (RESTBotAware) –

    The REST bot this modal client should be bound to.

  • alluka (Optional[Client], default: None ) –

    The Alluka client to use for callback dependency injection in this client.

    If not provided then this will initialise its own Alluka client.

  • bot_managed (bool, default: False ) –

    Whether the modal client should be automatically opened and closed based on the Bot's startup and shutdown callbacks.

Returns:

from_tanjun classmethod #

from_tanjun(tanjun_client, /, *, tanjun_managed=True)

Build a modal client from a Tanjun client.

This will use the Tanjun client's alluka client and registers ModalClient as a type dependency on Tanjun.

Parameters:

  • tanjun_client (Client) –

    The Tanjun client this modal client should be bound to.

  • tanjun_managed (bool, default: True ) –

    Whether the modal client should be automatically opened and closed based on the Tanjun client's lifetime client callback.

Returns:

get_modal #

get_modal(custom_id)

Get the modal set for a custom ID.

Parameters:

  • custom_id (str) –

    The custom_id to get the modal for.

Returns:

  • AbstractModal | None –

    The callback for the custom_id, or None if it doesn't exist.

on_gateway_event async #

on_gateway_event(event)

Process an interaction create gateway event.

Parameters:

on_rest_request async #

on_rest_request(interaction)

Process a modal interaction REST request.

Parameters:

Returns:

open #

open()

Startup the modal client.

register_modal #

register_modal(custom_id, modal, /, *, timeout=_internal.NO_DEFAULT)

Register a modal for a custom ID.

Parameters:

  • custom_id (str) –

    The custom_id to register the modal for.

    This will be matched against interaction.custom_id.split(":", 1)[0], allowing metadata to be stored after a ":".

  • modal (AbstractModal) –

    The modal to register.

  • timeout (Union[AbstractTimeout, None, NoDefault], default: NO_DEFAULT ) –

    Timeout strategy for this modal.

    Passing None here will set NeverTimeout.

    This defaults to single use with a 2 minute timeout.

Returns:

  • Self –

    The modal client to allow chaining.

Raises:

  • ValueError –

    If custom_id is already registered.

    If ":" is in the custom ID.

ModalContext #

Bases: BaseContext[ModalInteraction]

The context used for modal triggers.

author property #

author

Author of this interaction.

cache property #

cache

Hikari cache instance this context's client was initialised with.

channel_id property #

channel_id

ID of the channel this interaction was triggered in.

client property #

client

The modal this context is bound to.

component_ids property #

component_ids

Mapping of match ID parts to metadata ID parts for the modal's components.

events property #

events

Object of the event manager this context's client was initialised with.

expires_at property #

expires_at

When this context expires.

After this time is reached, the message/response methods on this context will always raise hikari.NotFoundError.

has_been_deferred property #

has_been_deferred

Whether this context's initial response has been deferred.

This will be true if BaseContext.defer has been called.

has_responded property #

has_responded

Whether an initial response has been made to this context yet.

It's worth noting that a context must be either responded to or deferred within 3 seconds from it being received otherwise it'll be marked as failed.

This will be true if either BaseContext.respond, BaseContext.create_initial_response or BaseContext.edit_initial_response (after a deferral) has been called.

id_match property #

id_match

Section of the ID used to identify the relevant executor.

id_metadata property #

id_metadata

Metadata from the interaction's custom ID.

interaction property #

interaction

Object of the interaction this context is for.

rest property #

rest

Object of the Hikari REST client this context's client was initialised with.

server property #

server

Object of the Hikari interaction server provided for this context's client.

shard property #

shard

Shard that triggered the interaction.

Note

This will be None if BaseContext.shards is also None.

shards property #

shards

Object of the Hikari shard manager this context's client was initialised with.

voice property #

voice

Object of the Hikari voice component this context's client was initialised with.

create_followup async #

create_followup(content=hikari.UNDEFINED, *, delete_after=None, ephemeral=None, attachment=hikari.UNDEFINED, attachments=hikari.UNDEFINED, component=hikari.UNDEFINED, components=hikari.UNDEFINED, embed=hikari.UNDEFINED, embeds=hikari.UNDEFINED, mentions_everyone=hikari.UNDEFINED, user_mentions=hikari.UNDEFINED, role_mentions=hikari.UNDEFINED, tts=hikari.UNDEFINED, flags=hikari.UNDEFINED)

Create a followup response for this context.

Warning

Calling this on a context which hasn't had an initial response yet will lead to a hikari.NotFoundError being raised.

Parameters:

Returns:

  • Message –

    The created message object.

Raises:

  • NotFoundError –

    If the current interaction is not found or it hasn't had an initial response yet.

  • BadRequestError –

    This can be raised if the file is too large; if the embed exceeds the defined limits; if the message content is specified only and empty or greater than 2000 characters; if neither content, file or embeds are specified. If any invalid snowflake IDs are passed; a snowflake may be invalid due to it being outside of the range of a 64 bit integer.

  • ValueError –

    If more than 100 unique objects/entities are passed for role_mentions or `user_mentions.

    If the interaction will have expired before delete_after is reached.

    If both attachment and attachments are passed or both component and components are passed or both embed and embeds are passed.

create_initial_response async #

create_initial_response(content=hikari.UNDEFINED, *, response_type=hikari.ResponseType.MESSAGE_CREATE, delete_after=None, ephemeral=None, attachment=hikari.UNDEFINED, attachments=hikari.UNDEFINED, component=hikari.UNDEFINED, components=hikari.UNDEFINED, embed=hikari.UNDEFINED, embeds=hikari.UNDEFINED, mentions_everyone=hikari.UNDEFINED, user_mentions=hikari.UNDEFINED, role_mentions=hikari.UNDEFINED, flags=hikari.UNDEFINED, tts=hikari.UNDEFINED)

Create the initial response for this context.

Warning

Calling this on a context which already has an initial response will result in this raising a hikari.NotFoundError. This includes if the REST interaction server has already responded to the request and deferrals.

Parameters:

Raises:

  • ValueError –

    If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

    If the interaction will have expired before delete_after is reached.

    If both attachment and attachments are passed or both component and components are passed or both embed and embeds are passed.

  • BadRequestError –

    This may be raised in several discrete situations, such as messages being empty with no embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; invalid image URLs in embeds.

  • UnauthorizedError –

    If you are unauthorized to make the request (invalid/missing token).

  • NotFoundError –

    If the interaction is not found or if the interaction's initial response has already been created.

  • RateLimitTooLongError –

    Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

  • InternalServerError –

    If an internal error occurs on Discord while handling the request.

defer async #

defer(*, defer_type=hikari.ResponseType.DEFERRED_MESSAGE_CREATE, ephemeral=None, flags=hikari.UNDEFINED)

Defer the initial response for this context.

Note

The ephemeral state of the first response is decided by whether the deferral is ephemeral.

Parameters:

delete_initial_response async #

delete_initial_response()

Delete the initial response after invoking this context.

Raises:

delete_last_response async #

delete_last_response()

Delete the last response after invoking this context.

Raises:

edit_initial_response async #

edit_initial_response(content=hikari.UNDEFINED, *, delete_after=None, attachment=hikari.UNDEFINED, attachments=hikari.UNDEFINED, component=hikari.UNDEFINED, components=hikari.UNDEFINED, embed=hikari.UNDEFINED, embeds=hikari.UNDEFINED, mentions_everyone=hikari.UNDEFINED, user_mentions=hikari.UNDEFINED, role_mentions=hikari.UNDEFINED)

Edit the initial response for this context.

Parameters:

Returns:

  • Message –

    The message that has been edited.

Raises:

  • ValueError –

    If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

    If delete_after would be more than 15 minutes after the interaction was received.

    If both attachment and attachments are passed or both component and components are passed or both embed and embeds are passed.

  • BadRequestError –

    This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds; too many components.

  • UnauthorizedError –

    If you are unauthorized to make the request (invalid/missing token).

  • ForbiddenError –

    If you are missing the SEND_MESSAGES in the channel or the person you are trying to message has the DM's disabled.

  • NotFoundError –

    If the channel is not found.

  • RateLimitTooLongError –

    Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

  • InternalServerError –

    If an internal error occurs on Discord while handling the request.

edit_last_response async #

edit_last_response(content=hikari.UNDEFINED, *, delete_after=None, attachment=hikari.UNDEFINED, attachments=hikari.UNDEFINED, component=hikari.UNDEFINED, components=hikari.UNDEFINED, embed=hikari.UNDEFINED, embeds=hikari.UNDEFINED, mentions_everyone=hikari.UNDEFINED, user_mentions=hikari.UNDEFINED, role_mentions=hikari.UNDEFINED)

Edit the last response for this context.

Parameters:

Returns:

  • Message –

    The message that has been edited.

Raises:

  • ValueError –

    If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

    If delete_after would be more than 15 minutes after the slash interaction was received.

    If both attachment and attachments are passed or both component and components are passed or both embed and embeds are passed.

  • BadRequestError –

    This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds; too many components.

  • UnauthorizedError –

    If you are unauthorized to make the request (invalid/missing token).

  • ForbiddenError –

    If you are missing the SEND_MESSAGES in the channel or the person you are trying to message has the DM's disabled.

  • NotFoundError –

    If the channel is not found.

  • RateLimitTooLongError –

    Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

  • InternalServerError –

    If an internal error occurs on Discord while handling the request.

fetch_initial_response async #

fetch_initial_response()

Fetch the initial response for this context.

Returns:

  • Message –

    The initial response's message object.

Raises:

fetch_last_response async #

fetch_last_response()

Fetch the last response for this context.

Returns:

  • Message –

    The most response response's message object.

Raises:

respond async #

respond(content=hikari.UNDEFINED, *, ensure_result=False, delete_after=None, attachment=hikari.UNDEFINED, attachments=hikari.UNDEFINED, component=hikari.UNDEFINED, components=hikari.UNDEFINED, embed=hikari.UNDEFINED, embeds=hikari.UNDEFINED, mentions_everyone=hikari.UNDEFINED, user_mentions=hikari.UNDEFINED, role_mentions=hikari.UNDEFINED)

Respond to this context.

Parameters:

Returns:

  • Message | None –

    The message that has been created if it was immedieatly available or ensure_result was set to True, else None.

Raises:

  • ValueError –

    If more than 100 unique objects/entities are passed for role_mentions or user_mentions.

    If delete_after would be more than 15 minutes after the interaction was received.

    If both attachment and attachments are passed or both component and components are passed or both embed and embeds are passed.

  • BadRequestError –

    This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds; too many components.

  • UnauthorizedError –

    If you are unauthorized to make the request (invalid/missing token).

  • ForbiddenError –

    If you are missing the SEND_MESSAGES in the channel or the person you are trying to message has the DM's disabled.

  • NotFoundError –

    If the channel is not found.

  • RateLimitTooLongError –

    Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

  • InternalServerError –

    If an internal error occurs on Discord while handling the request.

set_ephemeral_default #

set_ephemeral_default(state)

Set the ephemeral default state for this context.

Parameters:

  • state (bool) –

    The new ephemeral default state.

    If this is True then all calls to the response creating methods on this context will default to being ephemeral.

ModalOptions #

Data class used to define a modal's options.

Examples:

class ModalOptions(modals.ModalOptions):
    field: str = modals.text_input("label")
    optional_field: str | None = modals.text_input("label", default=None)

@modals.as_modal_template
async def modal_template(
    ctx: modals.Context, fields: ModalOptions,
) -> None:
    ...

WaitForModal #

Bases: AbstractModal, AbstractTimeout

Executor used to wait for a single modal interaction.

This should also be passed for timeout=.

Examples:

executor = yuyo.modals.WaitFor(timeout=datetime.timedelta(seconds=30))
modal_client.register_modal("custom_id", executor, timeout=executor)

await ctx.create_modal_response("Title", "custom_id", components=[...])

try:
    result = await executor.wait_for()
except asyncio.TimeoutError:
    await ctx.respond("Timed out")
else:
    await result.respond("...")

__init__ #

__init__(*, ephemeral_default=False, timeout=_DEFAULT_TIMEOUT)

Initialise a wait for executor.

Parameters:

  • ephemeral_default (bool, default: False ) –

    Whether or not the responses made on contexts spawned from this paginator should default to ephemeral (meaning only the author can see them) unless flags is specified on the response method.

  • timeout (Optional[timedelta], default: _DEFAULT_TIMEOUT ) –

    How long this should wait for a matching interaction until it times-out.

wait_for async #

wait_for()

Wait for the next matching interaction.

Returns:

  • Context –

    The next matching interaction.

Raises:

as_modal #

as_modal(callback=None, /, *, ephemeral_default=False, parse_signature=False)

Create a modal instance through a decorator call.

Info

This won't parse the callback for parameter descriptors and ModalOptions unless parse_signature=True is passed, unlike as_modal_template and Modal subclasses.

Parameters:

  • ephemeral_default (bool, default: False ) –

    Whether this modal's responses should default to ephemeral.

  • parse_signature (bool, default: False ) –

    Whether to parse the signature for parameter descriptors and ModalOptions type-hints.

Returns:

  • Modal –

    The new decorated modal.

as_modal_template #

as_modal_template(callback=None, /, *, ephemeral_default=False, parse_signature=True)

Create a modal template through a decorator callback.

The return type acts like any other slotted modal subclass and supports the same decorators and parameter descriptors for declaring the modal's entries.

Parameters:

  • ephemeral_default (bool, default: False ) –

    Whether this modal template's responses should default to ephemeral.

  • parse_signature (bool, default: True ) –

    Whether to parse the signature for parameter descriptors and ModalOptions type-hints.

Returns:

  • type[Modal] –

    The new decorated modal class.

modal #

modal(callback, /, *, ephemeral_default=False, parse_signature=False)

Create a modal instance for a callback.

Info

This won't parse the callback for parameter descriptors and ModalOptions unless parse_signature=True is passed, unlike as_modal_template and Modal subclasses.

Parameters:

  • callback (Callable[_P, _CoroT[None]]) –

    Callback to use for modal execution.

  • ephemeral_default (bool, default: False ) –

    Whether this modal's responses should default to ephemeral.

  • parse_signature (bool, default: False ) –

    Whether to parse the signature for parameter descriptors and ModalOptions type-hints.

Returns:

  • Modal –

    The created modal.

text_input #

text_input(label, /, *, custom_id=None, style=hikari.TextInputStyle.SHORT, placeholder=hikari.UNDEFINED, value=hikari.UNDEFINED, default=NO_DEFAULT, min_length=0, max_length=4000)

Descriptor used to declare a text input field.

Parameters:

  • label (str) –

    The text input field's display label.

    This cannot be greater than 45 characters long.

  • custom_id (Optional[str], default: None ) –

    The field's custom ID.

    Defaults to the name of the parameter/attribute this is assigned to.

  • style (TextInputStyle, default: SHORT ) –

    The text input's style.

  • placeholder (UndefinedOr[str], default: UNDEFINED ) –

    Placeholder text to display when the text input is empty.

  • value (UndefinedOr[str], default: UNDEFINED ) –

    Default text to pre-fill the field with.

  • default (Union[_T, Literal[VALUE]], default: NO_DEFAULT ) –

    Default value to pass if this text input field was not provided.

    The field will be marked as required unless this is supplied.

    This will also be used for value when it has been left undefined and the default is a string that's <=4000 characters in length.

  • min_length (int, default: 0 ) –

    Minimum length the input text can be.

    This can be greater than or equal to 0 and less than or equal to 4000.

  • max_length (int, default: 4000 ) –

    Maximum length the input text can be.

    This can be greater than or equal to 1 and less than or equal to 4000.

Examples:

This can either be applied to an argument's default

@modals.as_modal_template
async def modal_template(
    ctx: modals.Context,
    text_field: str = modals.text_input("label"),
    optional_field: str | None = modals.text_input("label", default=None)
) -> None:
    ...

Or as an attribute to a ModalOptions dataclass.

class ModalOptions(modals.ModalOptions):
    field: str = modals.text_input("label")
    optional_field: str | None = modals.text_input("label", default=None)

@modals.as_modal_template
async def modal_template(
    ctx: modals.Context, fields: ModalOptions,
) -> None:
    ...

with_static_text_input #

with_static_text_input(label, /, *, custom_id=None, style=hikari.TextInputStyle.SHORT, placeholder=hikari.UNDEFINED, value=hikari.UNDEFINED, default=NO_DEFAULT, min_length=0, max_length=4000, parameter=None)

Add a static text input field to the decorated modal subclass.

Parameters:

  • label (str) –

    The text input field's display label.

    This cannot be greater than 45 characters long.

  • custom_id (Optional[str], default: None ) –

    The field's custom ID.

    Defaults to parameter, if provided, or a UUID and cannot be longer than 100 characters.

  • style (TextInputStyle, default: SHORT ) –

    The text input's style.

  • placeholder (UndefinedOr[str], default: UNDEFINED ) –

    Placeholder text to display when the text input is empty.

  • value (UndefinedOr[str], default: UNDEFINED ) –

    Default text to pre-fill the field with.

  • default (Any, default: NO_DEFAULT ) –

    Default value to pass if this text input field was not provided.

    The field will be marked as required unless this is supplied.

    This will also be used for value when it has been left undefined and the default is a string that's <=4000 characters in length.

  • min_length (int, default: 0 ) –

    Minimum length the input text can be.

    This can be greater than or equal to 0 and less than or equal to 4000.

  • max_length (int, default: 4000 ) –

    Maximum length the input text can be.

    This can be greater than or equal to 1 and less than or equal to 4000.

  • parameter (Optional[str], default: None ) –

    Name of the parameter the text for this field should be passed to.

    This will be of type str and may also be the value passed for default.

Returns:

with_text_input #

with_text_input(label, /, *, custom_id=None, style=hikari.TextInputStyle.SHORT, placeholder=hikari.UNDEFINED, value=hikari.UNDEFINED, default=NO_DEFAULT, min_length=0, max_length=4000, parameter=None)

Add a text input field to the decorated modal instance.

Parameters:

  • label (str) –

    The text input field's display label.

    This cannot be greater than 45 characters long.

  • custom_id (Optional[str], default: None ) –

    The field's custom ID.

    Defaults to parameter, if provided, or a UUID and cannot be longer than 100 characters.

  • style (TextInputStyle, default: SHORT ) –

    The text input's style.

  • placeholder (UndefinedOr[str], default: UNDEFINED ) –

    Placeholder text to display when the text input is empty.

  • value (UndefinedOr[str], default: UNDEFINED ) –

    Default text to pre-fill the field with.

  • default (Any, default: NO_DEFAULT ) –

    Default value to pass if this text input field was not provided.

    The field will be marked as required unless this is supplied.

    This will also be used for value when it has been left undefined and the default is a string that's <=4000 characters in length.

  • min_length (int, default: 0 ) –

    Minimum length the input text can be.

    This can be greater than or equal to 0 and less than or equal to 4000.

  • max_length (int, default: 4000 ) –

    Maximum length the input text can be.

    This can be greater than or equal to 1 and less than or equal to 4000.

  • parameter (Optional[str], default: None ) –

    Name of the parameter the text for this field should be passed to.

    This will be of type str and may also be the value passed for default.

Returns:

  • Modal –

    The decorated modal instance.