ILLEST Developers

illest.py 2.3.1

Views, layouts and forms (ui)

## Layouts ## Forms

Read from the library itself: every signature and every word here is its own docstring.

View

class

illest.ui.View

class View(*, timeout: 'float | None' = 180.0)

timeout

property

children

property

add_item

add_item(item: 'Item') -> "'View'"

remove_item

remove_item(item: 'Item') -> "'View'"

clear_items

clear_items() -> "'View'"

get_item

get_item(custom_id: 'str') -> 'Item | None'

is_persistent

is_persistent() -> 'bool'

is_finished

is_finished() -> 'bool'

is_dispatching

is_dispatching() -> 'bool'

is_dispatchable

is_dispatchable() -> 'bool'

interaction_check

async
async interaction_check(interaction: "'Interaction'") -> 'bool'

Return False to refuse an interaction before its item's callback runs.

on_timeout

async
async on_timeout() -> 'None'

Runs once the view has gone timeout seconds without an interaction.

on_error

async
async on_error(interaction: "'Interaction'", error: 'Exception', item: 'Item') -> 'None'

stop

stop() -> 'None'

wait

async
async wait() -> 'bool'

Wait until the view stops; True when it timed out.

to_components

to_components() -> 'list[dict[str, Any]]'

The rows as the wire carries them: up to five, each up to five buttons or one select menu.

from_message

classmethod
from_message(message: "'Message'", /, *, timeout: 'float | None' = 180.0) -> "'View'"

Button

classfrom Item

illest.ui.Button

class Button(*, style: 'ButtonStyle | str' = <ButtonStyle.secondary: 'secondary'>, label: 'str | None' = None, disabled: 'bool' = False, custom_id: 'str | None' = None, url: 'str | None' = None, emoji: 'Any' = None, row: 'int | None' = None, sku_id: 'int | None' = None, id: 'int | None' = None)

A button under a message. custom_id names it to the bot; a link button (url=) opens an address instead.

is_dispatchable

is_dispatchable() -> 'bool'

is_persistent

is_persistent() -> 'bool'

to_wire

to_wire() -> 'dict[str, Any]'

from_wire

classmethod
from_wire(d: 'dict[str, Any]') -> "'Button'"

button

module

illest.ui.button

Button and the @ui.button decorator.

Button

class
class Button(*, style: 'ButtonStyle | str' = <ButtonStyle.secondary: 'secondary'>, label: 'str | None' = None, disabled: 'bool' = False, custom_id: 'str | None' = None, url: 'str | None' = None, emoji: 'Any' = None, row: 'int | None' = None, sku_id: 'int | None' = None, id: 'int | None' = None)

A button under a message. custom_id names it to the bot; a link button (url=) opens an address instead.

button

button(*, label: 'str | None' = None, custom_id: 'str | None' = None, disabled: 'bool' = False, style: 'ButtonStyle | str' = <ButtonStyle.secondary: 'secondary'>, emoji: 'Any' = None, row: 'int | None' = None, id: 'int | None' = None) -> 'Callable[[Callable], Callable]'

On a View subclass: async def method(self, interaction, button) runs when the button is pressed.

Select

classfrom BaseSelect

illest.ui.Select

class Select(*, options: 'Sequence[SelectOption] | None' = None, **kwargs: 'Any')

A menu of the bot's own choices. values is what was picked, as the options' value strings.

add_option

add_option(*, label: 'str', value: 'Any' = None, description: 'str | None' = None, emoji: 'Any' = None, default: 'bool' = False) -> 'None'

append_option

append_option(option: 'SelectOption') -> 'None'

to_wire

to_wire() -> 'dict[str, Any]'

from_wire

classmethod
from_wire(d: 'dict[str, Any]') -> "'Select'"

UserSelect

class

illest.ui.UserSelect

class UserSelect(*, default_values: 'Sequence[Any]' = (), **kwargs: 'Any')

Pick members of the server (or accounts the bot knows, in a direct conversation).

RoleSelect

class

illest.ui.RoleSelect

class RoleSelect(*, default_values: 'Sequence[Any]' = (), **kwargs: 'Any')

ChannelSelect

class

illest.ui.ChannelSelect

class ChannelSelect(*, channel_types: 'Sequence[ChannelType]' = (), **kwargs: 'Any')

to_wire

to_wire() -> 'dict[str, Any]'

MentionableSelect

class

illest.ui.MentionableSelect

class MentionableSelect(*, default_values: 'Sequence[Any]' = (), **kwargs: 'Any')

select

module

illest.ui.select

Select menus: Select (choices the bot lists), UserSelect, RoleSelect, MentionableSelect, ChannelSelect, and @ui.select.

A pick reaches the bot sealed in the conversation, so any member could seal one naming values the menu never offered. The library keeps only what the menu offers: for Select, its options' values; for the others, ids of accounts, roles or channels the bot knows in that server.

SelectOption

class
class SelectOption(*, label: 'str', value: 'Any' = None, description: 'str | None' = None, emoji: 'Any' = None, default: 'bool' = False)

DefaultSelectValue

class
class DefaultSelectValue(*, id: 'int', type: 'str')

Select

class
class Select(*, options: 'Sequence[SelectOption] | None' = None, **kwargs: 'Any')

A menu of the bot's own choices. values is what was picked, as the options' value strings.

UserSelect

class
class UserSelect(*, default_values: 'Sequence[Any]' = (), **kwargs: 'Any')

Pick members of the server (or accounts the bot knows, in a direct conversation).

RoleSelect

class
class RoleSelect(*, default_values: 'Sequence[Any]' = (), **kwargs: 'Any')

MentionableSelect

class
class MentionableSelect(*, default_values: 'Sequence[Any]' = (), **kwargs: 'Any')

ChannelSelect

class
class ChannelSelect(*, channel_types: 'Sequence[ChannelType]' = (), **kwargs: 'Any')

select

select(*, cls: 'type[BaseSelect]' = <class 'illest.ui.select.Select'>, options: 'Sequence[SelectOption]' = (), channel_types: 'Sequence[ChannelType]' = (), placeholder: 'str | None' = None, custom_id: 'str | None' = None, min_values: 'int' = 1, max_values: 'int' = 1, disabled: 'bool' = False, default_values: 'Sequence[Any]' = (), row: 'int | None' = None, id: 'int | None' = None) -> 'Callable[[Callable], Callable]'

On a View subclass: async def method(self, interaction, select) runs when something is picked.

ActionRow

class

illest.ui.ActionRow

class ActionRow(*children: 'Any')

add_item

add_item(item: 'Item') -> "'ActionRow'"

LayoutView

classfrom View

illest.ui.LayoutView

class LayoutView(*, timeout: 'float | None' = 180.0)

A view laid out with containers, sections, text, pictures, files and rules, as well as buttons and select menus.

Declare its parts as class attributes, or add_item them; buttons and select menus anywhere inside run as a View's do.

add_item

add_item(item: 'Item') -> "'LayoutView'"

remove_item

remove_item(item: 'Item') -> "'LayoutView'"

clear_items

clear_items() -> "'LayoutView'"

children

property

The parts at the top of the layout, as they were added.

walk_children

walk_children() -> 'Iterator[Item]'

Every button and select menu, wherever it sits.

get_item

get_item(custom_id: 'str') -> 'Item | None'

is_persistent

is_persistent() -> 'bool'

is_dispatchable

is_dispatchable() -> 'bool'

to_components

to_components() -> 'list[dict[str, Any]]'

A layout's buttons are inside it, so it has no rows of its own.

to_layout

to_layout() -> 'list[dict[str, Any]]'

The layout as the wire carries it, checked against the reader's bounds.

Container

class

illest.ui.Container

class Container(*children: 'Item', accent_colour: 'Any' = None, accent_color: 'Any' = None, spoiler: 'bool' = False, id: 'int | None' = None)

A frame around its parts, with an accent colour down its side and an optional spoiler over it.

accent_color

property

add_item

add_item(item: 'Item') -> "'Container'"

walk_children

walk_children() -> 'Iterator[Item]'

to_layout

to_layout() -> 'dict[str, Any]'

Section

class

illest.ui.Section

class Section(*children: 'Any', accessory: 'Item', id: 'int | None' = None)

One to three texts with a thumbnail or a button beside them.

add_item

add_item(item: 'Any') -> "'Section'"

walk_children

walk_children() -> 'Iterator[Item]'

to_layout

to_layout() -> 'dict[str, Any]'

TextDisplay

class

illest.ui.TextDisplay

class TextDisplay(content: 'str', *, id: 'int | None' = None)

Text in the message's own markdown.

to_layout

to_layout() -> 'dict[str, Any]'

Thumbnail

class

illest.ui.Thumbnail

class Thumbnail(media: 'Any', *, description: 'str | None' = None, spoiler: 'bool' = False, id: 'int | None' = None)

A small picture beside a section's text.

to_picture

to_picture() -> 'dict[str, Any]'

MediaGallery

class

illest.ui.MediaGallery

class MediaGallery(*items: 'MediaGalleryItem', id: 'int | None' = None)

One to ten pictures, laid out as a grid.

add_item

add_item(*, media: 'Any', description: 'str | None' = None, spoiler: 'bool' = False) -> "'MediaGallery'"

append_item

append_item(item: 'MediaGalleryItem') -> "'MediaGallery'"

to_layout

to_layout() -> 'dict[str, Any]'

File

class

illest.ui.File

class File(media: 'Any', *, spoiler: 'bool' = False, id: 'int | None' = None)

One of the message's own files, shown where the layout puts it: attachment://<filename>.

to_layout

to_layout() -> 'dict[str, Any]'

Separator

class

illest.ui.Separator

class Separator(*, visible: 'bool' = True, spacing: 'SeparatorSpacing' = <SeparatorSpacing.small: 1>, id: 'int | None' = None)

Space between parts, with a rule across it unless visible=False.

to_layout

to_layout() -> 'dict[str, Any]'

Modal

classfrom View

illest.ui.Modal

class Modal(*, title: 'str | None' = None, timeout: 'float | None' = None, custom_id: 'str | None' = None)

A form of up to five parts. Declare them as class attributes, or add_item them; override on_submit.

on_submit

async
async on_submit(interaction: "'Interaction'") -> 'None'

Runs once the form comes back filled in.

on_error

async
async on_error(interaction: "'Interaction'", error: 'Exception', item: 'Item | None' = None) -> 'None'

to_wire

to_wire() -> 'dict[str, Any]'

TextInput

class

illest.ui.TextInput

class TextInput(*, label: 'str | None' = None, style: 'TextStyle | str' = <TextStyle.short: 'short'>, custom_id: 'str | None' = None, placeholder: 'str | None' = None, default: 'str | None' = None, required: 'bool' = True, min_length: 'int | None' = None, max_length: 'int | None' = None, row: 'int | None' = None, description: 'str | None' = None, id: 'int | None' = None)

Text: one line, or several with style=TextStyle.long. value is what was typed, once submitted.

value

property

to_wire

to_wire() -> 'dict[str, Any]'

NumberInput

class

illest.ui.NumberInput

class NumberInput(*, label: 'str | None' = None, custom_id: 'str | None' = None, placeholder: 'str | None' = None, default: 'float | None' = None, min_value: 'float | None' = None, max_value: 'float | None' = None, integer: 'bool' = False, required: 'bool' = True, description: 'str | None' = None, id: 'int | None' = None)

A number, between min_value and max_value, and whole when integer is set. value is an int or a float, or None when left empty.

value

property

to_wire

to_wire() -> 'dict[str, Any]'

RadioGroup

class

illest.ui.RadioGroup

class RadioGroup(*, options: 'Sequence[SelectOption]' = (), label: 'str | None' = None, custom_id: 'str | None' = None, required: 'bool' = True, description: 'str | None' = None, id: 'int | None' = None)

One of a few choices, all in view. value is the chosen option's value, or None when left empty.

add_option

add_option(*, label: 'str', value: 'Any' = None, description: 'str | None' = None, default: 'bool' = False) -> 'None'

value

property

to_wire

to_wire() -> 'dict[str, Any]'

CheckboxGroup

class

illest.ui.CheckboxGroup

class CheckboxGroup(*, options: 'Sequence[SelectOption]' = (), label: 'str | None' = None, custom_id: 'str | None' = None, min_values: 'int' = 0, max_values: 'int | None' = None, required: 'bool' = True, description: 'str | None' = None, id: 'int | None' = None)

Any of a few choices, each with its own box. values is the ticked options' values.

add_option

add_option(*, label: 'str', value: 'Any' = None, description: 'str | None' = None, default: 'bool' = False) -> 'None'

values

property

to_wire

to_wire() -> 'dict[str, Any]'

Checkbox

class

illest.ui.Checkbox

class Checkbox(*, label: 'str | None' = None, custom_id: 'str | None' = None, default: 'bool' = False, required: 'bool' = False, description: 'str | None' = None, id: 'int | None' = None)

One box to tick. value is True when ticked; a required one has to be ticked, as "I agree" does.

value

property

to_wire

to_wire() -> 'dict[str, Any]'

FileUpload

class

illest.ui.FileUpload

class FileUpload(*, label: 'str | None' = None, custom_id: 'str | None' = None, min_values: 'int' = 1, max_values: 'int' = 1, file_types: 'Sequence[str]' = (), required: 'bool' = True, description: 'str | None' = None, id: 'int | None' = None)

Files the person picks from their device, sealed like the ones they send. values is a list of illest.Attachment.

file_types narrows what can be picked: "image", "video", "audio", or endings such as ".pdf".

values

property

to_wire

to_wire() -> 'dict[str, Any]'

Label

class

illest.ui.Label

class Label(*, text: 'str', component: 'Item', description: 'str | None' = None, id: 'int | None' = None) -> 'Item'

A title and a line of description for one part of a form: any field or select menu.

ui.Label(text="Team", description="Pick the one you play for", component=ui.RadioGroup(...)) is the part itself, titled, so self.team.value reads the answer.