Skip to content

yuyo#

A collection of utility functions and classes designed to expand Hikari.

LocalizedPage module-attribute #

LocalizedPage = LocalisedPage

Alias of LocalisedPage.

ActionColumnExecutor #

Bases: AbstractComponentExecutor

Executor which handles columns of action rows.

This can be used to declare and handle the components on a message a couple of ways.

To send a column's components pass ActionColumnExecutor.rows as components when calling the create message method (e.g. respond/create_message).

Examples:

Sub-components can be added to an instance of the column executor using chainable methods on it:

async def callback_1(ctx: components.Context) -> None:
    await ctx.respond("meow")

components = (
    components.ActionColumnExecutor()
    .add_interactive_button(hikari.ButtonStyle.PRIMARY, chainable, label="Button 1")
    .add_link_button("https://example.com", label="Button 2",)
)

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

Note

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

async def callback_1(ctx: components.Context) -> None:
    await ctx.respond("meow")

async def callback_2(ctx: components.Context) -> None:
    await ctx.respond("meow")

@components.with_static_select_menu(callback_1, hikari.ComponentType.USER_SELECT_MENU, max_values=5)
class CustomColumn(components.ActionColumnExecutor):
    __slots__ = ("special_string",)  # ActionColumnExecutor supports slotting.

    # The init can be overridden to store extra data on the column object when subclassing.
    def __init__(self, special_string: str, timeout: typing.Optional[datetime.timedelta] = None):
        super().__init__(timeout=timeout)
        self.special_string = special_string

(
    CustomColumn.add_static_text_menu(callback_2, min_values=0, max_values=3)
    # The following calls are all adding options to the added
    # text select menu.
    .add_option("Option 1", "value 1")
    .add_option("Option 2", "value 2")
    .add_option("Option 3", "value 3")
)

There's also class descriptors which can be used to declare static components. The following descriptors work by decorating their component's callback:

link_button returns a descriptor without decorating any callback.

class CustomColumn(components.ActionColumnExecutor):
    @components.as_interactive_button(ButtonStyle.PRIMARY, label="label")
    async def left_button(self, ctx: components.Context) -> None:
        ...

    link_button = components.link_button(url="https://example.com", label="Go to page")

    @components.as_interactive_button(ButtonStyle.SECONDARY, label="meow")
    async def right_button(self, ctx: components.Context) -> None:
        ...

    @components.as_channel_menu(channel_types=[hikari.TextableChannel], custom_id="eep")
    async def text_select_menu(self, ctx: components.Context) -> None:
        ...

rows property #

rows

The rows in this column.

__init__ #

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

Initialise an action column executor.

Parameters:

  • authors (Optional[Iterable[SnowflakeishOr[User]]], default: None ) –

    Users who are allowed to use the components this represents.

    If no users are provided then the components will be public (meaning that anybody can use it).

  • ephemeral_default (bool, default: False ) –

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

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

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

    The keys in this can either be the match part of component custom IDs or the names of the component's callback when it was added using one of the as_ class descriptors.

add_builder #

add_builder(builder)

Add a raw component builder to this action column.

This is mostly for adding components where the custom ID is already registered as a separate constant executor.

Parameters:

add_channel_menu #

add_channel_menu(callback, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_interactive_button #

add_interactive_button(style, callback, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to this action column.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

  • callback (CallbackSig) –

    The button's execution callback.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_link_button(url, /, *, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a link button to this action column.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    The action column to enable chained calls.

add_mentionable_menu #

add_mentionable_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_role_menu #

add_role_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_select_menu #

add_select_menu(type_, callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a select menu to this action column.

The following methods should be used instead:

add_static_builder classmethod #

add_static_builder(builder)

Add a raw component builder to all subclasses and instances of this column.

This is mostly for adding components where the custom ID is already registered as a separate constant executor.

Parameters:

  • builder (ComponentBuilder) –

    The component builder to add to the column class.

add_static_channel_menu classmethod #

add_static_channel_menu(callback, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_interactive_button classmethod #

add_static_interactive_button(style, callback, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to all subclasses and instances of this action column class.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

  • callback (CallbackSig) –

    The button's execution callback.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_link_button(url, /, *, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a link button to all subclasses and instances of this action column class.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_mentionable_menu classmethod #

add_static_mentionable_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_role_menu classmethod #

add_static_role_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_select_menu classmethod #

add_static_select_menu(type_, callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a select menu to all subclasses and instances of this action column class.

The following class methods should be used instead:

add_static_text_menu classmethod #

add_static_text_menu(callback, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added by calling TextSelectMenuBuilder.add_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

Raises:

add_static_user_menu classmethod #

add_static_user_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_text_menu #

add_text_menu(callback, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added by calling TextSelectMenuBuilder.add_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

add_user_menu #

add_user_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

with_channel_menu #

with_channel_menu(callback=None, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column through a decorator call.

Parameters:

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_interactive_button #

with_interactive_button(style, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to this action column through a decorator call.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

with_mentionable_menu #

with_mentionable_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_role_menu #

with_role_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_static_channel_menu classmethod #

with_static_channel_menu(callback=None, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column class through a decorator call.

Parameters:

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_interactive_button classmethod #

with_static_interactive_button(style, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a static interactive button to this action column class through a decorator call.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Raises:

with_static_mentionable_menu classmethod #

with_static_mentionable_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static mentionable select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_role_menu classmethod #

with_static_role_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static role select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_text_menu classmethod #

with_static_text_menu(callback=None, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added using [yuyo.components.with_option].

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_user_menu classmethod #

with_static_user_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static user select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_text_menu #

with_text_menu(callback=None, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column through a decorator callback.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added using components.with_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_user_menu #

with_user_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

AsgiAdapter #

Asgi/3 adapter for Hikari's interaction server interface.

For this to work, hikari has to be installed with the optional "server" feature (e.g python -m pip install hikari[server]).

server property #

server

The interaction server this adapter is bound to.

__call__ async #

__call__(scope, receive, send)

Call the adapter.

Note

This method is called by the ASGI server.

Parameters:

  • scope (Scope) –

    The scope of the request.

  • receive (ASGIReceiveCallable) –

    The receive function to use.

  • send (ASGISendCallable) –

    The send function to use.

Raises:

__init__ #

__init__(server, /, *, executor=None, max_body_size=1024 ** 2)

Initialise the adapter.

Parameters:

  • server (InteractionServer) –

    The interaction server to use.

  • executor (Optional[Executor], default: None ) –

    If non-None, then this executor is used instead of the concurrent.futures.ThreadPoolExecutor attached to the asyncio.AbstractEventLoop that the bot will run on. This executor is used primarily for file-IO.

    While mainly supporting the concurrent.futures.ThreadPoolExecutor implementation in the standard lib, Hikari's file handling systems should also work with concurrent.futures.ProcessPoolExecutor, which relies on all objects used in IPC to be pickleable. Many third-party libraries will not support this fully though, so your mileage may vary on using ProcessPoolExecutor implementations with this parameter.

  • max_body_size (int, default: 1024 ** 2 ) –

    The maximum body size this should allow received request bodies to be in bytes before failing the request with a 413 - Content Too Large.

add_shutdown_callback #

add_shutdown_callback(callback)

Add a callback to be called when the ASGI server shuts down.

Warning

These callbacks will block the ASGI server from shutting down until they complete and any raised errors will lead to a failed shutdown.

Parameters:

Returns:

  • Self –

    The adapter to enable chained calls.

add_startup_callback #

add_startup_callback(callback)

Add a callback to be called when the ASGI server starts up.

Warning

These callbacks will block the ASGI server from starting until they complete and any raised errors will lead to a failed startup.

Parameters:

Returns:

  • Self –

    The adapter to enable chained calls.

remove_shutdown_callback #

remove_shutdown_callback(callback)

Remove a shutdown callback.

Parameters:

Returns:

  • Self –

    The adapter to enable chained calls.

Raises:

  • ValueError –

    If the callback was not registered.

remove_startup_callback #

remove_startup_callback(callback)

Remove a startup callback.

Parameters:

Returns:

  • Self –

    The adapter to enable chained calls.

Raises:

  • ValueError –

    If the callback was not registered.

AsgiBot #

Bases: RESTBotAware

Bot implementation which acts as an ASGI adapter.

This bot doesn't initiate a server internally but instead relies on being called as an ASGI app.

For this to work, hikari has to be installed with the optional "server" feature (e.g python -m pip install hikari[server]).

__call__ async #

__call__(scope, receive, send)

Call the bot with an ASGI event.

Note

This method is called by the ASGI server and allows the bot to function like AsgiAdapter.

Parameters:

  • scope (Scope) –

    The scope of the request.

  • receive (ASGIReceiveCallable) –

    The receive function to use.

  • send (ASGISendCallable) –

    The send function to use.

Raises:

__init__ #

__init__(token, token_type=None, public_key=None, *, asgi_managed=True, executor=None, http_settings=None, max_body_size=1024 ** 2, max_rate_limit=300.0, max_retries=3, proxy_settings=None, rest_url=None)

Initialise a new ASGI bot.

Parameters:

  • token (Union[str, TokenStrategy]) –

    The bot or bearer token. If no token is to be used, this can be undefined.

  • token_type (Union[TokenType, str, None], default: None ) –

    The type of token in use. This should only be passed when str is passed for token, can be "Bot" or "Bearer" and will be defaulted to "Bot" in this situation.

    This should be left as None when either hikari.api.TokenStrategy or None is passed for token.

  • asgi_managed (bool, default: True ) –

    Whether this bot's internal components should be automatically started and stopped based on the Asgi lifespan events.

  • executor (Optional[Executor], default: None ) –

    If non-None, then this executor is used instead of the concurrent.futures.ThreadPoolExecutor attached to the asyncio.AbstractEventLoop that the bot will run on. This executor is used primarily for file-IO.

    While mainly supporting the concurrent.futures.ThreadPoolExecutor implementation in the standard lib, Hikari's file handling systems should also work with concurrent.futures.ProcessPoolExecutor, which relies on all objects used in IPC to be pickleable. Many third-party libraries will not support this fully though, so your mileage may vary on using ProcessPoolExecutor implementations with this parameter.

  • http_settings (Optional[HTTPSettings], default: None ) –

    Optional custom HTTP configuration settings to use. Allows you to customise functionality such as whether SSL-verification is enabled, what timeouts aiohttp should expect to use for requests, and behavior regarding HTTP-redirects.

  • max_body_size (int, default: 1024 ** 2 ) –

    The maximum body size this should allow received request bodies to be in bytes before failing the request with a 413 - Content Too Large.

  • max_rate_limit (float, default: 300.0 ) –

    The max number of seconds to backoff for when rate limited. Anything greater than this will instead raise an error.

    This defaults to five minutes to stop potentially indefinitely waiting on an endpoint, which is almost never what you want to do if giving a response to a user.

    You can set this to float("inf") to disable this check entirely. Note that this only applies to the REST API component that communicates with Discord, and will not affect sharding or third party HTTP endpoints that may be in use.

  • max_retries (int, default: 3 ) –

    Maximum number of times a request will be retried if

    it fails with a 5xx status. Defaults to 3 if set to None.

  • proxy_settings (Optional[ProxySettings], default: None ) –

    Custom proxy settings to use with network-layer logic in your application to get through an HTTP-proxy.

  • public_key (Union[bytes, str, None], default: None ) –

    The public key to use to verify received interaction requests.

    This may be a hex encoded str or the raw bytes. If left as None then the client will try to work this value out based on token.

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

    Defaults to the Discord REST API URL if None. Can be overridden if you are attempting to point to an unofficial endpoint, or if you are attempting to mock/stub the Discord API for any reason.

    Generally you do not want to change this.

Raises:

  • ValueError –
    • If token_type is provided when a token strategy is passed for token.
    • if token_type is left as None when a string is passed for token.

add_shutdown_callback #

add_shutdown_callback(callback)

Add a callback to be called when the bot shuts down.

Warning

These callbacks will block the bot from shutting down until they complete and any raised errors will lead to a failed shutdown.

Parameters:

add_startup_callback #

add_startup_callback(callback)

Add a callback to be called when the bot starts up.

Warning

These callbacks will block the bot from starting until they complete and any raised errors will lead to a failed startup.

Parameters:

close async #

close()

Close the bot's REST client.

Warning

Unless asgi_managed=False is passed to AsgiBot.__init__, the bot will be automatically closed based on the ASGI lifespan events and any other calls to this function will raise a RuntimeError.

Raises:

  • RuntimeError –

    If the client isn't alive. If the client is ASGI managed.

remove_shutdown_callback #

remove_shutdown_callback(callback)

Remove a shutdown callback.

Parameters:

Raises:

  • ValueError –

    If the callback was not registered.

remove_startup_callback #

remove_startup_callback(callback)

Remove a startup callback.

Parameters:

Raises:

  • ValueError –

    If the callback was not registered.

run #

run()

Start the bot's REST client and wait until the bot's closed.

Warning

Unless asgi_managed=False is passed to AsgiBot.__init__, the bot will be automatically started and closed based on the ASGI lifespan events and any other calls to this function will raise a RuntimeError.

Raises:

  • RuntimeError –

    If the client is already alive. If the client is ASGI managed.

start async #

start()

Start the bot's REST client.

Warning

Unless asgi_managed=False is passed to AsgiBot.__init__, the bot will be automatically started based on the ASGI lifespan events and any other calls to this function will raise a RuntimeError.

Raises:

  • RuntimeError –

    If the client is already alive. If the client is ASGI managed.

Backoff #

Used to exponentially backoff asynchronously.

This class acts as an asynchronous iterator and can be iterated over to provide implicit backoff where for every iteration other than the first this will either back off for the time passed to Backoff.set_next_backoff if applicable or a time calculated exponentially.

Each iteration yields the current retry count (starting at 0).

Examples:

An example of using this class as an asynchronous iterator may look like the following

# While we can directly do `async for _ in Backoff()`, by assigning it to a
# variable we allow ourself to provide a specific backoff time in some cases.
backoff = Backoff()
async for _ in backoff:
    response = await client.fetch(f"https://example.com/{resource_id}")
    if response.status_code == 403:  # Ratelimited
        # If we have a specific backoff time then set it for the next iteration
        backoff.set_next_backoff(response.headers.get("Retry-After"))

    elif response.status_code >= 500:  # Internal server error
        # Else let the iterator calculate an exponential backoff before the next loop.
        pass

    else:
        response.raise_for_status()
        resource = response.json()
        # We need to break out of the iterator to make sure it doesn't backoff again.
        # Alternatively `Backoff.finish()` can be called to break out of the loop.
        break

Alternatively you may want to explicitly call Backoff.backoff. An alternative implementation of the previous example which uses Backoff.backoff may look like the following:

backoff = Backoff()
resource = None
while not resource:
    response = await client.fetch(f"https://example.com/{resource_id}")
    if response == 403  # Ratelimited
        # If we have a specific backoff time then set it for the next iteration.
        backoff.set_next_backoff(response.headers.get("Retry-After"))
        await backoff.backoff()  # We must explicitly backoff in this flow.

    elif response >= 500:  # Internal server error
        # Else let the iterator calculate an exponential backoff and explicitly backoff.
        await backoff.backoff()

    else:
        response.raise_for_status()
        resource = response.json()

is_depleted property #

is_depleted

Whether "max_retries" has been reached.

This can be used to workout whether the loop was explicitly broken out of using Backoff.finish/break or if it hit "max_retries".

__init__ #

__init__(max_retries=None, *, base=2.0, maximum=64.0, jitter_multiplier=1.0, initial_increment=0)

Initialise a backoff instance.

Parameters:

  • max_retries (Optional[int], default: None ) –

    The maximum amount of times this should iterate for between resets.

    If left as None then this iterator will be unlimited. This must be greater than or equal to 1.

  • base (float, default: 2.0 ) –

    The base to use.

  • maximum (float, default: 64.0 ) –

    The max value the backoff can be in a single iteration. Anything above this will be capped to this base value plus random jitter.

  • jitter_multiplier (float, default: 1.0 ) –

    The multiplier for the random jitter.

    Set to 0 to disable jitter.

  • initial_increment (int, default: 0 ) –

    The initial increment to start at.

Raises:

  • ValueError –

    If an int that's too big to be represented as a float or a non-finite value is passed in place of a field that's annotated as float or if max_retries is less than 1.

backoff async #

backoff()

Sleep for the provided backoff or for the next exponent.

This provides an alternative to iterating over this class.

Returns:

  • int | None –

    Whether this has reached the end of its iteration.

    If this returns True then that call didn't sleep as this has been marked as finished or has reached the max retries.

finish #

finish()

Mark the iterator as finished to break out of the current loop.

reset #

reset()

Reset the backoff to it's original state to reuse it.

set_next_backoff #

set_next_backoff(backoff_)

Specify a backoff time for the next iteration or Backoff.backoff call.

If this is called then the exponent won't be increased for this iteration.

Note

Calling this multiple times in a single iteration will overwrite any previously set next backoff.

Parameters:

  • backoff_ (Union[float, int, None]) –

    The amount of time to backoff for in seconds.

    If this is None then any previously set next backoff will be unset.

BotsGGService #

https://discord.bots.gg status update service.

__init__ #

__init__(token)

Initialise a bots.gg service.

Parameters:

  • token (str) –

    Authorization token used to update the bot's status.

ChunkRequestFinishedEvent #

Bases: ShardEvent

Event that's dispatched when a specific chunk request has finished.

This will be fired for every chunk request which has a nonce.

chunk_count property #

chunk_count

The amount of chunk events which should've been received for this request.

first_received_at property #

first_received_at

When the first response was received.

guild_id property #

guild_id

Id of the guild this chunk request was for.

last_received_at property #

last_received_at

When the last response was received.

missed_chunks property #

missed_chunks

Collection of the chunk responses which were missed (if any).

not_found_ids property #

not_found_ids

Collection of the User IDs which weren't found.

This is only relevant when users was specified while requesting the members.

__init__ #

__init__(app, shard, data)

Initialise a chunk request finished event.

This should never be initialised directly.

ChunkTracker #

Chunk payload event tracker.

This will dispatch ShardFinishedChunkingEvent, FinishedChunkingEvent and ChunkRequestFinishedEvent events.

To configure this to automatically request member chunks to fill a member and/or presence cache on startup and guild join see ChunkTracker.set_auto_chunk_members.

Note

ChunkTracker.request_guild_members ensures a request will be tracked as this only tracks chunk requests with a set nonce.

__init__ #

__init__(event_manager, rest, shards, /, *, timeout=datetime.timedelta(seconds=5))

Initialise a chunk tracker.

For a shorthand for initialising this from a hikari.GatewayBotAware see ChunkTracker.from_gateway_bot.

Parameters:

  • event_manager (EventManager) –

    The event manager this chunk tracker should dispatch events over.

  • rest (RESTAware) –

    The REST aware object this should use.

  • shards (ShardAware) –

    The shard aware object this should use.

  • timeout (Union[int, float, timedelta], default: timedelta(seconds=5) ) –

    How long this should wait between chunks until deciding the request has finished early/incomplete.

from_gateway_bot classmethod #

from_gateway_bot(bot, /, *, timeout=datetime.timedelta(seconds=5))

Initialise a chunk tracker from a gateway bot.

Parameters:

request_guild_members async #

request_guild_members(guild, /, *, include_presences=hikari.UNDEFINED, query='', limit=0, users=hikari.UNDEFINED)

Request guild members.

Note

To request the full list of members, leave query as "" (empty string) and limit as 0.

Parameters:

Raises:

  • ValueError –

    When trying to specify users with query/limit, if limit is not between 0 and 100, both inclusive or if users length is over 100.

  • MissingIntentError –

    When trying to request presences without the GUILD_MEMBERS or when trying to request the full list of members without GUILD_PRESENCES.

set_auto_chunk_members #

set_auto_chunk_members(state, /, *, chunk_presences=True)

Configure whether this should request member chunks in response to GUILD_CREATE.

This may be useful for filling 3rd party caches but may conflict with the auto_chunk_members config of hikari.impl.GatewayBot if it's enabled.

Warning

This will be ignored if Intents.GUILD_MEMBERS hasn't been declared.

Parameters:

  • state (bool) –

    Whether this should request member chunks when GUILD_CREATE events are received.

  • chunk_presences (bool, default: True ) –

    Whether this should also request member presences on these member chunks.

    This will be ignored if Intents.GUILD_PRESENCES hasn't been declared.

Returns:

  • Self –

    The chunk tracker object to enable call chaining.

ComponentClient #

Client used to handle component executors 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 component client.

This sets ComponentClient as a type dependency when alluka isn't passed.

Note

For an easier way to initialise the client from a bot see ComponentClient.from_gateway_bot, ComponentClient.from_rest_bot, and ComponentClient.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 component 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 component interactions from if applicable.

Raises:

close #

close()

Close the component client.

deregister_executor #

deregister_executor(executor)

Remove a component executor by its custom IDs.

Parameters:

Returns:

  • Self –

    The component client to allow chaining.

Raises:

  • KeyError –

    If the executor isn't registered.

deregister_message #

deregister_message(message)

Remove a component executor by its message.

Parameters:

Returns:

  • Self –

    The component client to allow chaining.

Raises:

  • KeyError –

    If the message is not registered.

from_gateway_bot classmethod #

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

Build a component client from a Gateway Bot.

This sets ComponentClient as a type dependency when alluka isn't passed.

Parameters:

  • bot (_GatewayBotProto) –

    The Gateway bot this component 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 component 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 component client from a REST Bot.

This sets ComponentClient as a type dependency when alluka isn't passed.

Parameters:

  • bot (RESTBotAware) –

    The REST bot this component 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 component 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 component client from a Tanjun client.

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

Parameters:

  • tanjun_client (Client) –

    The Tanjun client this component client should be bound to.

  • tanjun_managed (bool, default: True ) –

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

Returns:

get_executor #

get_executor(custom_id)

Get the component executor registered for a custom ID.

Note

For message scoped executors use get_executor_for_message. as they will not be returned here.

Parameters:

  • custom_id (str) –

    The custom ID to get the executor for.

Returns:

get_executor_for_message #

get_executor_for_message(message)

Get the component executor registered for a message.

Parameters:

Returns:

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 component interaction REST request.

Parameters:

Returns:

  • ResponseT –

    The REST response.

open #

open()

Startup the component client.

register_executor #

register_executor(executor, /, *, message=None, timeout=_internal.NO_DEFAULT)

Add an executor to this client.

Parameters:

  • executor (AbstractComponentExecutor) –

    The executor to register.

  • message (Optional[SnowflakeishOr[Message]], default: None ) –

    The message to register this executor for.

    If this is left as None then this executor will be registered globally for its custom IDs.

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

    The executor's timeout.

    This defaults to a 30 second sliding timeout.

Returns:

  • Self –

    The component client to allow chaining.

Raises:

  • ValueError –

    If message is already registered when it's passed.

    If any of the executor's custom IDs are already registered when message wasn't passed.

ComponentContext #

Bases: BaseContext[ComponentInteraction]

The context used for message component triggers.

alluka property #

alluka

The Alluka client being used for callback dependency injection.

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 component client this context is bound to.

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.

selected_channels property #

selected_channels

Sequence of the users passed for a channel select menu.

selected_members property #

selected_members

Sequence of the members passed for a user select menu.

This will also include some of the values for a mentionable select menu.

selected_roles property #

selected_roles

Sequence of the users passed for a role select menu.

This will also include some of the values for a mentionable select menu.

selected_texts property #

selected_texts

Sequence of the values passed for a text select menu.

selected_users property #

selected_users

Sequence of the users passed for a user select menu.

This will also include some of the values for a mentionable select menu.

ComponentContext.selected_members has the full member objects.

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.

create_modal_response async #

create_modal_response(title, custom_id, /, *, component=hikari.UNDEFINED, components=hikari.UNDEFINED)

Send a modal as the initial response for this context.

Warning

This must be called as the first response to a context before any deferring.

Parameters:

  • title (str) –

    The title that will show up in the modal.

  • custom_id (str) –

    Developer set custom ID used for identifying interactions with this modal.

    Yuyo's Component client will only match against custom_id.split(":", 1)[0], allowing metadata to be put after ":".

  • component (UndefinedOr[ComponentBuilder], default: UNDEFINED ) –

    A component builder to send in this modal.

  • components (UndefinedOr[Sequence[ComponentBuilder]], default: UNDEFINED ) –

    A sequence of component builders to send in this modal.

Raises:

  • ValueError –

    If both component and components are specified or if none are specified.

  • BadRequestError –

    When the requests' data is outside Discord's accept ranges/validation.

  • 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 or deferred.

  • 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.

ComponentExecutor #

Bases: AbstractComponentExecutor

implementation of a component executor with per-custom ID callbacks.

callbacks property #

callbacks

Mapping of custom IDs to their set callbacks.

__init__ #

__init__(*, ephemeral_default=False)

Initialise a component executor.

Parameters:

  • ephemeral_default (bool, default: False ) –

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

set_callback #

set_callback(custom_id, callback)

Set the callback for a custom ID.

Parameters:

  • custom_id (str) –

    The custom ID to set the callback for.

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

  • callback (CallbackSig) –

    The callback to set.

Raises:

with_callback #

with_callback(custom_id)

Set the callback for a custom ID through a decorator callback.

Parameters:

  • custom_id (str) –

    The custom ID to set the callback for.

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

Returns:

Raises:

ComponentPaginator #

Bases: ActionColumnExecutor

Standard implementation of an action row executor used for pagination.

This is a convenience class that allows you to easily implement a paginator.

Note

This doesn't use action column's "static" components so any static components added to base-classes of this will appear before the pagination components.

rows property #

rows

The rows in this column.

__init__ #

__init__(iterator, /, *, authors=None, ephemeral_default=False, triggers=(pagination.LEFT_TRIANGLE, pagination.STOP_SQUARE, pagination.RIGHT_TRIANGLE))

Initialise a component paginator.

Parameters:

add_builder #

add_builder(builder)

Add a raw component builder to this action column.

This is mostly for adding components where the custom ID is already registered as a separate constant executor.

Parameters:

add_channel_menu #

add_channel_menu(callback, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_first_button #

add_first_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=None, emoji=pagination.LEFT_DOUBLE_TRIANGLE, label=hikari.UNDEFINED, is_disabled=False)

Add the jump to first entry button to this paginator.

You should pass triggers=[] to ComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_interactive_button #

add_interactive_button(style, callback, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to this action column.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

  • callback (CallbackSig) –

    The button's execution callback.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_last_button #

add_last_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=None, emoji=pagination.RIGHT_DOUBLE_TRIANGLE, label=hikari.UNDEFINED, is_disabled=False)

Add the jump to last entry button to this paginator.

You should pass triggers=[] to ComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_link_button(url, /, *, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a link button to this action column.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    The action column to enable chained calls.

add_mentionable_menu #

add_mentionable_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_next_button #

add_next_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=None, emoji=pagination.RIGHT_TRIANGLE, label=hikari.UNDEFINED, is_disabled=False)

Add the next entry button to this paginator.

You should pass triggers=[] to ComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_previous_button #

add_previous_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=None, emoji=pagination.LEFT_TRIANGLE, label=hikari.UNDEFINED, is_disabled=False)

Add the previous entry button to this paginator.

You should pass triggers=[] to ComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT, default: SECONDARY ) –

    The button's style.

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

    Custom ID to use for identifying button presses.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: LEFT_TRIANGLE ) –

    Emoji to display on this button.

    Either this or label must be provided, but not both.

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

    Label to display on this button.

    Either this or emoji must be provided, but not both.

  • is_disabled (bool, default: False ) –

    Whether to make this button as disabled.

Returns:

  • Self –

    To enable chained calls.

add_role_menu #

add_role_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_select_menu #

add_select_menu(type_, callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a select menu to this action column.

The following methods should be used instead:

add_static_builder classmethod #

add_static_builder(builder)

Add a raw component builder to all subclasses and instances of this column.

This is mostly for adding components where the custom ID is already registered as a separate constant executor.

Parameters:

  • builder (ComponentBuilder) –

    The component builder to add to the column class.

add_static_channel_menu classmethod #

add_static_channel_menu(callback, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_interactive_button classmethod #

add_static_interactive_button(style, callback, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to all subclasses and instances of this action column class.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

  • callback (CallbackSig) –

    The button's execution callback.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_link_button(url, /, *, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a link button to all subclasses and instances of this action column class.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_mentionable_menu classmethod #

add_static_mentionable_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_role_menu classmethod #

add_static_role_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_select_menu classmethod #

add_static_select_menu(type_, callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a select menu to all subclasses and instances of this action column class.

The following class methods should be used instead:

add_static_text_menu classmethod #

add_static_text_menu(callback, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added by calling TextSelectMenuBuilder.add_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

Raises:

add_static_user_menu classmethod #

add_static_user_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_stop_button #

add_stop_button(*, style=hikari.ButtonStyle.DANGER, custom_id=None, emoji=pagination.BLACK_CROSS, label=hikari.UNDEFINED, is_disabled=False)

Add the stop button to this paginator.

You should pass triggers=[] to ComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT, default: DANGER ) –

    The button's style.

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

    Custom ID to use for identifying button presses.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: BLACK_CROSS ) –

    Emoji to display on this button.

    Either this or label must be provided, but not both.

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

    Label to display on this button.

    Either this or emoji must be provided, but not both.

  • is_disabled (bool, default: False ) –

    Whether to make this button as disabled.

Returns:

  • Self –

    To enable chained calls.

add_text_menu #

add_text_menu(callback, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added by calling TextSelectMenuBuilder.add_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

add_user_menu #

add_user_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

get_next_entry async #

get_next_entry()

Get the next entry in this paginator.

This is generally helpful for making the message which the paginator will be based off and will still internally store the entry and increment the position of the paginator.

Examples:

paginator = yuyo.ComponentPaginator(pages, authors=[ctx.author.id])
first_response = await paginator.get_next_entry()
assert first_response
message = await ctx.respond(components=paginator.rows, **first_response.to_kwargs(), ensure_result=True)
component_client.register_executor(paginator, message=message)

Returns:

  • AbstractPage | None –

    The next entry in this paginator, or None if there are no more entries.

with_channel_menu #

with_channel_menu(callback=None, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column through a decorator call.

Parameters:

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_interactive_button #

with_interactive_button(style, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to this action column through a decorator call.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

with_mentionable_menu #

with_mentionable_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_role_menu #

with_role_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_static_channel_menu classmethod #

with_static_channel_menu(callback=None, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column class through a decorator call.

Parameters:

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_interactive_button classmethod #

with_static_interactive_button(style, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a static interactive button to this action column class through a decorator call.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Raises:

with_static_mentionable_menu classmethod #

with_static_mentionable_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static mentionable select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_role_menu classmethod #

with_static_role_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static role select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_text_menu classmethod #

with_static_text_menu(callback=None, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added using [yuyo.components.with_option].

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_user_menu classmethod #

with_static_user_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static user select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_text_menu #

with_text_menu(callback=None, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column through a decorator callback.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added using components.with_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_user_menu #

with_user_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

DiscordBotListService #

https://discordbotlist.com status update service.

__init__ #

__init__(token)

Initialise a discordbotlist.com service.

Parameters:

  • token (str) –

    Authorization token used to update the bot's status.

ErrorManager #

A context manager provided to allow for more concise error handling with Backoff.

Examples:

The following is an example of using ErrorManager alongside Backoff in-order to handle the exceptions which may be raised while trying to reply to a message.

retry = Backoff()
# Rules can either be passed to `ErrorManager`'s initiate as variable arguments
# or one at a time to `ErrorManager.with_rule` through possibly chained-calls.
error_handler = (
    # For the 1st rule we catch two errors which would indicate the bot
    # no-longer has access to the target channel and break out of the
    # retry loop using `Backoff.retry`.
    ErrorManager(((NotFoundError, ForbiddenError), lambda _: retry.finish()))
        # For the 2nd rule we catch rate limited errors and set their
        # `retry` value as the next backoff time before suppressing the
        # error to allow this to retry the request.
        .with_rule((RateLimitedError,), lambda exc: retry.set_next_backoff(exc.retry_after))
        # For the 3rd rule we suppress the internal server error to allow
        # backoff to reach the next retry and exponentially backoff as we
        # don't have any specific retry time for this error.
        .with_rule((InternalServerError,), lambda _: False)
)
async for _ in retry:
    # We entre this context manager each iteration to catch errors before
    # they cause us to break out of the `Backoff` loop.
    with error_handler:
        await post(f"https://example.com/{resource_id}", json={"content": "General Kenobi"})
        # We need to break out of `retry` if this request succeeds.
        break

__init__ #

__init__(*rules)

Initialise an error manager instance.

Parameters:

  • *rules (tuple[Iterable[type[BaseException]], Callable[[Any], Optional[bool]]], default: () ) –

    Rules to initiate this error context manager with.

    These are each a 2-length tuple where the tuple[0] is an iterable of types of the exceptions this rule should apply to and tuple[1] is the rule's callback function.

    The callback function will be called with the raised exception when it matches one of the passed exceptions for the relevant rule and may raise, return True to indicate that the current error should be raised outside of the context manager or False/None to suppress the current error.

add_rule #

add_rule(exceptions, result)

Add a rule to this exception context manager.

Parameters:

  • exceptions (Iterable[type[BaseException]]) –

    An iterable of types of the exceptions this rule should apply to.

  • result (Callable[[Any], Optional[bool]]) –

    The function called with the raised exception when it matches one of the passed exceptions. This may raise, return True to indicate that the current error should be raised outside of the context manager or False/None to suppress the current error.

Returns:

  • Self –

    This returns the handler a rule was being added to in-order to allow for chained calls.

clear_rules #

clear_rules()

Clear the rules registered with this handler.

FinishedChunkingEvent #

Bases: Event

Event that's dispatched when the startup chunking has finished for the bot.

This indicates that the member and presence caches should be complete globally.

This will only be fired once after bot startups.

__init__ #

__init__(app)

Initialise a chunking finished event.

This should never be initialised directly.

InteractionError #

Bases: Exception

Error which is sent as a response to a modal or component call.

__init__ #

__init__(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)

Initialise an interaction error.

Parameters:

Raises:

  • ValueError –

    Raised for any of the following reasons:

    • When both attachment and attachments are provided.
    • When both component and components are passed.
    • When both embed and embeds are passed.
    • If more than 100 entries are passed for role_mentions.
    • If more than 100 entries are passed for user_mentions.

send async #

send(ctx, /, *, ensure_result=False)

Send this error as an interaction response.

Parameters:

Raises:

  • ValueError –

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

  • 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.

LocalisedPage #

Bases: AbstractPage

Implementation of a paginated response which returns locale specific pages..

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.

alluka property #

alluka

The Alluka client being used for callback dependency injection.

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.

Page #

Bases: AbstractPage

Represents a pagianted response.

__init__ #

__init__(content=hikari.UNDEFINED, *, attachment=hikari.UNDEFINED, attachments=hikari.UNDEFINED, embed=hikari.UNDEFINED, embeds=hikari.UNDEFINED)

Initialise a response page.

Parameters:

Raises:

  • ValueError –

    Raised for any of the following reasons:

    • When both attachment and attachments are provided.
    • When both embed and embeds are passed.

ctx_to_kwargs #

ctx_to_kwargs(_)

Form create message **kwargs for this page based on a component or modal context.

Returns:

from_entry classmethod #

from_entry(entry)

Create a Page from a EntryT.

Parameters:

Returns:

to_kwargs #

to_kwargs()

Form create message **kwargs for this page.

Returns:

ReactionClient #

A class which handles the events for multiple registered reaction handlers.

alluka property #

alluka

The Alluka client being used for callback dependency injection.

is_closed property #

is_closed

Whether this client is closed.

__init__ #

__init__(*, rest, event_manager, alluka=None, event_managed=True)

Initialise a reaction client.

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

Note

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

Parameters:

  • rest (RESTClient) –

    The REST client to register this reaction client with.

  • event_manager (EventManager) –

    The event manager client to register this reaction client with.

  • 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 reaction client should be automatically opened and closed based on the lifetime events dispatched by event_managed.

close async #

close()

Close this client by unregistering any registered tasks and event listeners.

from_gateway_bot classmethod #

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

Build a ReactionClient from a gateway bot.

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

Parameters:

  • bot (EventManagerAware & RESTAware) –

    The bot to build a reaction client for.

  • 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 reaction client should be automatically opened and closed based on the lifetime events dispatched by bot.

Returns:

from_tanjun classmethod #

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

Build a ReactionClient from a gateway bot.

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

Parameters:

  • tanjun_client (Client) –

    The tanjun client to build a reaction client for.

  • tanjun_managed (bool, default: True ) –

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

Returns:

Raises:

get_handler #

get_handler(message)

Get a reference to a handler registered in this reaction client.

Note

This does not call AbstractReactionHandler.close.

Parameters:

Returns:

open async #

open()

Start this client by registering the required tasks and event listeners for it to function.

remove_handler #

remove_handler(message)

Remove a handler from this reaction client.

Note

This does not call AbstractReactionHandler.close.

Parameters:

Returns:

set_handler #

set_handler(message, handler)

Add a reaction handler to this reaction client.

Note

This does not call AbstractReactionHandler.open.

Parameters:

ReactionHandler #

Bases: AbstractReactionHandler

Standard basic implementation of a reaction handler.

authors property #

authors

Set of the authors/owner of a enabled handler.

Note

If this is empty then the handler is considered public and any user will be able to trigger it.

__init__ #

__init__(*, authors=(), timeout=datetime.timedelta(seconds=30))

Initialise a reaction handler.

Parameters:

  • authors (Iterable[SnowflakeishOr[User]], default: () ) –

    An iterable of IDs of the users who can call this handler.

    If no users are provided then the reactions will be public (meaning that anybody can use it).

  • timeout (Optional[timedelta], default: timedelta(seconds=30) ) –

    How long it should take for this handler to timeout.

remove_callback #

remove_callback(emoji_identifier)

Remove a callback from this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji the callback to remove is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

set_callback #

set_callback(emoji_identifier, callback)

Add a callback to this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji this callback is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

  • callback (CallbackSig) –

    The callback to add.

    This should be a function that accepts a single parameter, which is the event that triggered this reaction.

with_callback #

with_callback(emoji_identifier)

Add a callback to this reaction handler through a decorator call.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji this callback is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

Returns:

ReactionPaginator #

Bases: ReactionHandler

Standard implementation of a reaction handler for pagination.

authors property #

authors

Set of the authors/owner of a enabled handler.

Note

If this is empty then the handler is considered public and any user will be able to trigger it.

__init__ #

__init__(iterator, /, *, authors=(), triggers=(pagination.LEFT_TRIANGLE, pagination.STOP_SQUARE, pagination.RIGHT_TRIANGLE), timeout=datetime.timedelta(seconds=30))

Initialise a reaction paginator.

Parameters:

add_author #

add_author(user)

Add a author/owner to this handler.

Parameters:

add_first_button #

add_first_button(*, emoji=pagination.LEFT_DOUBLE_TRIANGLE, add_reaction=True)

Add the jump to first entry reaction button to this paginator.

You should pass triggers=[] to ReactionPaginator.__init__ before calling this.

Note

These reactions will appear in the order these methods were called in.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_last_button #

add_last_button(*, emoji=pagination.RIGHT_DOUBLE_TRIANGLE, add_reaction=True)

Add the jump to last entry reaction button to this paginator.

You should pass triggers=[] to ReactionPaginator.__init__ before calling this.

Note

These reactions will appear in the order these methods were called in.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_next_button #

add_next_button(*, emoji=pagination.RIGHT_TRIANGLE, add_reaction=True)

Add the next entry reaction button to this paginator.

You should pass triggers=[] to ReactionPaginator.__init__ before calling this.

Note

These reactions will appear in the order these methods were called in.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_previous_button #

add_previous_button(*, emoji=pagination.LEFT_TRIANGLE, add_reaction=True)

Add the previous entry reaction button to this paginator.

You should pass triggers=[] to ReactionPaginator.__init__ before calling this.

Note

These reactions will appear in the order these methods were called in.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_stop_button #

add_stop_button(*, emoji=pagination.STOP_SQUARE, add_reaction=True)

Add the stop reaction button to this paginator.

You should pass triggers=[] to ReactionPaginator.__init__ before calling this.

Note

These reactions will appear in the order these methods were called in.

Parameters:

Returns:

  • Self –

    To enable chained calls.

close async #

close(*, remove_reactions=False)

Close this handler and deregister any previously registered message.

Parameters:

  • remove_reactions (bool, default: False ) –

    Whether this should remove the reactions that were being used to paginate through this from the previously registered message.

create_message async #

create_message(rest, channel_id, /, *, add_reactions=True)

Start this handler and link it to a bot message.

Note

Calling this multiple times will replace the previously registered message.

Parameters:

  • rest (RESTClient) –

    Rest client to use to make the response.

  • channel_id (SnowflakeishOr[TextableChannel]) –

    ID of the channel to respond in.

  • add_reactions (bool, default: True ) –

    Whether this should add the paginator's reactions to the message after responding.

Returns:

  • Message –

    Object of the message this handler now targets. If message was not supplied then this will be the object of a newly created message, otherwise this will be what was supplied as message.

Raises:

  • ValueError –

    If the provided iterator didn't yield any content for the first message.

get_next_entry async #

get_next_entry()

Get the next entry in this paginator.

Returns:

  • AbstractPage | None –

    The next entry in this paginator, or None if there are no more entries.

open async #

open(message, /, *, add_reactions=True)

Start the reaction paginator and start accepting reactions..

Parameters:

  • message (Message) –

    The message this paginator should target.

  • add_reactions (bool, default: True ) –

    Whether this should add the paginator's reactions to the message.

remove_author #

remove_author(user)

Remove a author/owner from this handler.

Note

If the provided user isn't already a registered owner of this paginator then this should pass silently without raising.

Parameters:

remove_callback #

remove_callback(emoji_identifier)

Remove a callback from this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji the callback to remove is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

set_callback #

set_callback(emoji_identifier, callback)

Add a callback to this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji this callback is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

  • callback (CallbackSig) –

    The callback to add.

    This should be a function that accepts a single parameter, which is the event that triggered this reaction.

with_callback #

with_callback(emoji_identifier)

Add a callback to this reaction handler through a decorator call.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji this callback is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

Returns:

ServiceManager #

Bases: AbstractManager

Standard service manager.

is_alive property #

is_alive

Wwhether this manager is active.

__init__ #

__init__(rest, /, *, cache=None, event_manager=None, shards=None, event_managed=None, strategy=None, user_agent=None)

Initialise a service manager.

Note

For an easier way to initialise the manager from a bot see ServiceManager.from_gateway_bot, and ServiceManager.from_tanjun.

Parameters:

  • rest (RESTClient) –

    The RESTAware Hikari client to bind this manager to.

  • cache (Optional[Cache], default: None ) –

    The cache aware Hikari client this manager should use.

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

    The event manager aware Hikari client this manager should use.

  • shards (Optional[ShardAware], default: None ) –

    The shard aware Hikari client this manager should use.

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

    Whether this client should be automatically opened and closed based on event_manager's lifetime events.

    Defaults to True when event_manager is passed.

  • strategy (Optional[AbstractCountStrategy], default: None ) –

    The counter strategy this manager should expose to services.

    If this is left as None then the manager will try to pick a suitable standard strategy based on the provided Hikari clients.

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

    Override the standard user agent used during requests to bot list services.

Raises:

  • ValueError –

    If the manager failed to find a suitable standard strategy to use when strategy was left as None.

    If event_managed is passed as True when event_manager is None.

add_service #

add_service(service, /, *, repeat=datetime.timedelta(hours=1))

Add a service to this manager.

Parameters:

Returns:

  • Self –

    Object of this service manager.

Raises:

close async #

close()

Close this manager.

from_gateway_bot classmethod #

from_gateway_bot(bot, /, *, event_managed=True, strategy=None, user_agent=None)

Build a service manager from a gateway bot.

Parameters:

  • bot (ShardAware & RESTAware & EventManagerAware) –

    The gateway bot to build a service manager from.

  • event_managed (bool, default: True ) –

    Whether this client should be automatically opened and closed based on bot's lifetime events.

  • strategy (Optional[AbstractCountStrategy], default: None ) –

    The counter strategy this manager should expose to services.

    If this is left as None then the manager will try to pick a suitable standard strategy based on the provided Hikari clients.

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

    Override the standard user agent used during requests to bot list services.

Returns:

Raises:

  • ValueError –

    If the manager failed to find a suitable standard strategy to use when strategy was left as None.

from_tanjun classmethod #

from_tanjun(tanjun_client, /, *, tanjun_managed=True, strategy=None, user_agent=None)

Build a service manager from a Tanjun client.

This will use the Tanjun client's alluka client and registers ServiceManager and AbstractManager as type dependencies on Tanjun.

Parameters:

  • tanjun_client (Client) –

    The Tanjun client to build a service manager from.

  • tanjun_managed (bool, default: True ) –

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

  • strategy (Optional[AbstractCountStrategy], default: None ) –

    The counter strategy this manager should expose to services.

    If this is left as None then the manager will try to pick a suitable standard strategy based on the provided Hikari clients.

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

    Override the standard user agent used during requests to bot list services.

Returns:

Raises:

  • ValueError –

    If the manager failed to find a suitable standard strategy to use when strategy was left as None.

open async #

open()

Start this manager.

Raises:

remove_service #

remove_service(service)

Remove the first found entry of the registered service.

Parameters:

  • service (ServiceSig) –

    Service callback to unregister.

Raises:

with_service #

with_service(*, repeat=datetime.timedelta(hours=1))

Add a service to this manager by decorating a function.

Parameters:

Returns:

Raises:

ShardFinishedChunkingEvent #

Bases: ShardEvent

Event that's dispatched when the startup chunking has finished for a shard.

This indicates that the member and presence caches should be complete for guilds covered by this shard.

This will be fired after every shard identify which triggers chunking (including re-identifies).

incomplete_guild_ids property #

incomplete_guild_ids

Sequence of the IDs of guilds some chunk responses were missed for.

missed_guild_ids property #

missed_guild_ids

Sequence of the IDs of guilds no chunk responses were received for.

__init__ #

__init__(app, shard, /, *, incomplete_guild_ids=(), missed_guild_ids=())

Initialise a shard chunking finished event.

This should never be initialised directly.

SlidingTimeout #

Bases: AbstractTimeout

Timeout strategy which resets every use.

This implementation times out if timeout passes since the last call or when max_uses is reached.

__init__ #

__init__(timeout, /, *, max_uses=1)

Initialise a sliding timeout.

Parameters:

  • timeout (Union[timedelta, int, float]) –

    How long this should wait between calls before timing-out.

  • max_uses (int, default: 1 ) –

    The maximum amount of uses this allows.

    Setting this to -1 marks it as unlimited.

StaticComponentPaginator #

Bases: ActionColumnExecutor

Implementation of components for paginating static data.

This enables paginated responses to be persisted between bot restarts.

rows property #

rows

The rows in this column.

__init__ #

__init__(paginator_id, page_number, /, *, content_hash=None, ephemeral_default=False, include_buttons=True, id_metadata=None)

Initialise a static component paginator.

Parameters:

  • paginator_id (str) –

    ID of the paginator this targets.

    This is ignored when this is used to execute interactions.

  • page_number (int) –

    Index of the current page this paginator is on.

    This is ignored when this is used to execute interactions.

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

    Hash used to validate that the received interaction's components are still in-sync with the static data stored in this paginator.

  • ephemeral_default (bool, default: False ) –

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

  • include_buttons (bool, default: True ) –

    Whether to include the default buttons.

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

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

    This does not effect the standard buttons.

add_builder #

add_builder(builder)

Add a raw component builder to this action column.

This is mostly for adding components where the custom ID is already registered as a separate constant executor.

Parameters:

add_channel_menu #

add_channel_menu(callback, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_first_button #

add_first_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=_StaticPaginatorId.FIRST, emoji=pagination.LEFT_DOUBLE_TRIANGLE, id_metadata=None, label=hikari.UNDEFINED, is_disabled=False)

Add the jump to first entry button to this paginator.

You should pass include_buttons=False to StaticComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    To enable chained calls.

add_interactive_button #

add_interactive_button(style, callback, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to this action column.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

  • callback (CallbackSig) –

    The button's execution callback.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_last_button #

add_last_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=_StaticPaginatorId.LAST, emoji=pagination.RIGHT_DOUBLE_TRIANGLE, id_metadata=None, label=hikari.UNDEFINED, is_disabled=False)

Add the jump to last entry button to this paginator.

You should pass include_buttons=False to StaticComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT, default: SECONDARY ) –

    The button's style.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: RIGHT_DOUBLE_TRIANGLE ) –

    Emoji to display on this button.

    Either this or label must be provided, but not both.

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

    Mapping of keys to the values of extra metadata to include in this button's custom ID.

    This will be encoded as a url query string.

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

    Label to display on this button.

    Either this or emoji must be provided, but not both.

  • is_disabled (bool, default: False ) –

    Whether to make this button as disabled.

Returns:

  • Self –

    To enable chained calls.

add_link_button(url, /, *, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a link button to this action column.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • Self –

    The action column to enable chained calls.

add_mentionable_menu #

add_mentionable_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_next_button #

add_next_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=_StaticPaginatorId.NEXT, emoji=pagination.RIGHT_TRIANGLE, id_metadata=None, label=hikari.UNDEFINED, is_disabled=False)

Add the next entry button to this paginator.

You should pass include_buttons=False to StaticComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT, default: SECONDARY ) –

    The button's style.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: RIGHT_TRIANGLE ) –

    Emoji to display on this button.

    Either this or label must be provided, but not both.

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

    Mapping of keys to the values of extra metadata to include in this button's custom ID.

    This will be encoded as a url query string.

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

    Label to display on this button.

    Either this or emoji must be provided, but not both.

  • is_disabled (bool, default: False ) –

    Whether to make this button as disabled.

Returns:

  • Self –

    To enable chained calls.

add_previous_button #

add_previous_button(*, style=hikari.ButtonStyle.SECONDARY, custom_id=_StaticPaginatorId.PREVIOUS, emoji=pagination.LEFT_TRIANGLE, id_metadata=None, label=hikari.UNDEFINED, is_disabled=False)

Add the previous entry button to this paginator.

You should pass include_buttons=False to StaticComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT, default: SECONDARY ) –

    The button's style.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: LEFT_TRIANGLE ) –

    Emoji to display on this button.

    Either this or label must be provided, but not both.

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

    Mapping of keys to the values of extra metadata to include in this button's custom ID.

    This will be encoded as a url query string.

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

    Label to display on this button.

    Either this or emoji must be provided, but not both.

  • is_disabled (bool, default: False ) –

    Whether to make this button as disabled.

Returns:

  • Self –

    To enable chained calls.

add_role_menu #

add_role_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

add_select_button #

add_select_button(*, style=hikari.ButtonStyle.DANGER, custom_id=_StaticPaginatorId.SELECT, emoji=pagination.SELECT_PAGE_SYMBOL, id_metadata=None, label=hikari.UNDEFINED, is_disabled=False)

Add the select page button to this paginator.

You should pass include_buttons=False to StaticComponentPaginator.__init__ before calling this.

Note

These buttons will appear in the order these methods were called in.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT, default: DANGER ) –

    The button's style.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: SELECT_PAGE_SYMBOL ) –

    Emoji to display on this button.

    Either this or label must be provided, but not both.

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

    Mapping of keys to the values of extra metadata to include in this button's custom ID.

    This will be encoded as a url query string.

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

    Label to display on this button.

    Either this or emoji must be provided, but not both.

  • is_disabled (bool, default: False ) –

    Whether to make this button as disabled.

Returns:

  • Self –

    To enable chained calls.

add_select_menu #

add_select_menu(type_, callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a select menu to this action column.

The following methods should be used instead:

add_static_builder classmethod #

add_static_builder(builder)

Add a raw component builder to all subclasses and instances of this column.

This is mostly for adding components where the custom ID is already registered as a separate constant executor.

Parameters:

  • builder (ComponentBuilder) –

    The component builder to add to the column class.

add_static_channel_menu classmethod #

add_static_channel_menu(callback, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_interactive_button classmethod #

add_static_interactive_button(style, callback, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to all subclasses and instances of this action column class.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

  • callback (CallbackSig) –

    The button's execution callback.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_link_button(url, /, *, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a link button to all subclasses and instances of this action column class.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_mentionable_menu classmethod #

add_static_mentionable_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_role_menu classmethod #

add_static_role_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_static_select_menu classmethod #

add_static_select_menu(type_, callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a select menu to all subclasses and instances of this action column class.

The following class methods should be used instead:

add_static_text_menu classmethod #

add_static_text_menu(callback, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added by calling TextSelectMenuBuilder.add_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

Raises:

add_static_user_menu classmethod #

add_static_user_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to all subclasses and instances of this action column class.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • type[Self] –

    The action column class to enable chained calls.

Raises:

add_text_menu #

add_text_menu(callback, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added by calling TextSelectMenuBuilder.add_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

add_user_menu #

add_user_menu(callback, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to this action column.

Parameters:

  • callback (CallbackSig) –

    Callback which is called when this select menu is used.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Returns:

  • Self –

    The action column to enable chained calls.

with_channel_menu #

with_channel_menu(callback=None, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column through a decorator call.

Parameters:

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_interactive_button #

with_interactive_button(style, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add an interactive button to this action column through a decorator call.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

with_mentionable_menu #

with_mentionable_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a mentionable select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_role_menu #

with_role_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a role select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_static_channel_menu classmethod #

with_static_channel_menu(callback=None, /, *, custom_id=None, channel_types=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a channel select menu to this action column class through a decorator call.

Parameters:

  • channel_types (Optional[Sequence[Union[ChannelType, type[PartialChannel]]]], default: None ) –

    Sequence of the types of channels this select menu should show as options.

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_interactive_button classmethod #

with_static_interactive_button(style, /, *, custom_id=None, emoji=hikari.UNDEFINED, label=hikari.UNDEFINED, is_disabled=False)

Add a static interactive button to this action column class through a decorator call.

Either emoji xor label must be provided to be the button's displayed label.

Parameters:

  • style (InteractiveButtonTypesT) –

    The button's style.

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

    The button's custom ID.

    Defaults to 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.

  • emoji (Union[Snowflakeish, Emoji, str, UndefinedType], default: UNDEFINED ) –

    The button's emoji.

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

    The button's label.

  • is_disabled (bool, default: False ) –

    Whether the button should be marked as disabled.

Raises:

with_static_mentionable_menu classmethod #

with_static_mentionable_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static mentionable select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_role_menu classmethod #

with_static_role_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static role select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_text_menu classmethod #

with_static_text_menu(callback=None, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added using [yuyo.components.with_option].

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_static_user_menu classmethod #

with_static_user_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a static user select menu to this action column class through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

Raises:

with_text_menu #

with_text_menu(callback=None, /, *, custom_id=None, options=(), placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a text select menu to this action column through a decorator callback.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

  • options (Sequence[SelectOptionBuilder], default: () ) –

    The text select's options.

    These can also be added using components.with_option.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

with_user_menu #

with_user_menu(callback=None, /, *, custom_id=None, placeholder=hikari.UNDEFINED, min_values=0, max_values=1, is_disabled=False)

Add a user select menu to this action column through a decorator call.

Parameters:

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

    The select menu's custom ID.

    Defaults to 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.

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

    Placeholder text to show when no entries have been selected.

  • min_values (int, default: 0 ) –

    The minimum amount of entries which need to be selected.

  • max_values (int, default: 1 ) –

    The maximum amount of entries which can be selected.

  • is_disabled (bool, default: False ) –

    Whether this select menu should be marked as disabled.

StaticPaginatorIndex #

Index of all the static paginators within a bot.

not_found_response property #

not_found_response

Response that's sent by the default implementation when a paginator ID isn't found.

out_of_date_response property #

out_of_date_response

Response that's sent by the default implementation when content hashes don't match.

__init__ #

__init__(*, make_components=lambda paginator_id, page_number, content_hash: StaticComponentPaginator(paginator_id, page_number, content_hash=content_hash), make_modal=static_paginator_model, modal_title='Select page', not_found_response=None, out_of_date_response=None)

Initialise a static paginator index.

Parameters:

  • make_components (Callable[[str, int, Optional[str]], ActionColumnExecutor], default: lambda paginator_id, page_number, content_hash: StaticComponentPaginator(paginator_id, page_number, content_hash=content_hash) ) –

    Callback that's used to make the default pagination message components.

  • make_modal (Callable[[], Modal], default: static_paginator_model ) –

    Callback that's used to make a modal that handles the select page button.

  • modal_title (MaybeLocalsiedType[str], default: 'Select page' ) –

    Title of the modal that's sent when the select page button is pressed.

  • not_found_response (Optional[AbstractPage], default: None ) –

    The response to send when a paginator ID isn't found.

  • out_of_date_response (Optional[AbstractPage], default: None ) –

    The response to send when the content hashes don't match.

add_to_clients #

add_to_clients(component_client, modal_client)

Add this index to the component and modal clients to enable operation.

Parameters:

  • component_client (ComponentClient) –

    The component client to add this to.

  • modal_client (ModalClient) –

    The modal client to add this to.

callback async #

callback(ctx, page_number)

Execute a static paginator interaction.

Parameters:

create_select_modal async #

create_select_modal(ctx)

Create the standard modal used to handle the select page button.

Parameters:

  • ctx (ComponentContext) –

    The component context this modal is being made for.

get_paginator #

get_paginator(paginator_id)

Get a paginator.

Parameters:

  • paginator_id (str) –

    ID of the paginator to get.

Returns:

Raises:

  • KeyError –

    If no paginator was found.

remove_paginator #

remove_paginator(paginator_id)

Remove a static paginator.

Parameters:

  • paginator_id (str) –

    ID of the paginator to remove.

Raises:

  • KeyError –

    If no paginator was found.

set_paginator #

set_paginator(paginator_id, pages, /, *, content_hash=None)

Set the static paginator for a custom ID.

Parameters:

  • paginator_id (str) –

    ID that's used to identify this paginator.

  • pages (Sequence[AbstractPage]) –

    Sequence of the paginator's built pages.

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

    Content hash that's used to optionally ensure instances of the of the paginator's components are compatible with the bot's stored data.

Raises:

StaticTimeout #

Bases: AbstractTimeout

Timeout at a specific time.

This implementation times out when timeout_at is reached or when max_uses is reached.

__init__ #

__init__(timeout_at, /, *, max_uses=1)

Initialise a static timeout.

Parameters:

  • timeout_at (datetime) –

    When this should time out.

  • max_uses (int, default: 1 ) –

    The maximum amount of uses this allows.

    Setting this to -1 marks it as unlimited.

StreamExecutor #

Bases: AbstractComponentExecutor, AbstractTimeout

Stream over the received component interactions.

This should also be passed for timeout= and will reject contexts until it's opened.

Examples:

message = await ctx.respond("hi, pick an option", components=[...])
stream = yuyo.components.Stream(authors=[ctx.author.id], timeout=datetime.timedelta(seconds=30))
component_client.register_executor(stream, message=message, timeout=stream)

with stream:
    async for result in stream:
        await result.respond("...")

__init__ #

__init__(*, authors, custom_ids=(), ephemeral_default=False, max_backlog=5, timeout)

Initialise a stream executor.

Parameters:

  • authors (Optional[Iterable[SnowflakeishOr[User]]]) –

    Users who are allowed to use the components this represents.

    If None is passed here then the paginator will be public (meaning that anybody can use it).

  • custom_ids (Collection[str], default: () ) –

    Collection of the custom IDs this executor should be triggered by when registered globally.

  • 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.

  • max_backlog (int, default: 5 ) –

    The maximum amount of interaction contexts this should store in its backlog.

    Any extra interactions will be rejected while the backlog is full.

  • timeout (Union[float, int, timedelta, None]) –

    How long this should wait between iterations for a matching interaction to be recveived before ending the iteration.

    This alone does not close the stream.

TopGGService #

https://top.gg status update service.

__init__ #

__init__(token)

Initialise a top.gg service.

Parameters:

  • token (str) –

    Authorization token used to update the bot's status.

WaitForExecutor #

Bases: AbstractComponentExecutor, AbstractTimeout

Component executor used to wait for a single component interaction.

This should also be passed for timeout=.

Examples:

message = await ctx.respond("hi, pick an option", components=[...], ensure_result=True)

executor = yuyo.components.WaitFor(authors=[ctx.author.id], timeout=datetime.timedelta(seconds=30))
component_client.register_executor(executor, message=message, timeout=executor)

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

__init__ #

__init__(*, authors=None, custom_ids=(), ephemeral_default=False, timeout)

Initialise a wait for executor.

Parameters:

  • authors (Optional[Iterable[SnowflakeishOr[User]]], default: None ) –

    Users who are allowed to use the components this represents.

    If no users are provided then the components will be public (meaning that anybody can use it).

  • custom_ids (Collection[str], default: () ) –

    Collection of the custom IDs this executor should be triggered by when registered globally.

  • 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]) –

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

wait_for async #

wait_for()

Wait for the next matching interaction.

Returns:

  • Context –

    The next matching interaction.

Raises:

aenumerate async #

aenumerate(iterable)

Async equivalent of enumerate.

Parameters:

  • iterable (AsyncIterable[_T]) –

    The async iterable to enumerate.

Returns:

  • AsyncIterator[tuple[int, _T]] –

    The enumerated async iterator.

async_paginate_string async #

async_paginate_string(lines, /, *, char_limit=2000, line_limit=25, wrapper=None)

Lazily paginate an iterator of lines.

Parameters:

  • lines (AsyncIterable[str]) –

    The asynchronous iterator of lines to paginate.

  • char_limit (int, default: 2000 ) –

    The limit for how many characters should be included per yielded page.

  • line_limit (int, default: 25 ) –

    The limit for how many lines should be included per yielded page.

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

    A wrapper for each yielded page. This should leave "{}" in it to be replaced by the page's content.

Returns:

  • AsyncIterator[str] –

    An async iterator of each page's content.

paginate_string #

paginate_string(lines, /, *, char_limit=2000, line_limit=25, wrapper=None)

Lazily paginate an iterator of lines.

Parameters:

  • lines (Iterator[str] | AsyncIterator[str]) –

    The iterator of lines to paginate. This iterator may be asynchronous or synchronous.

  • char_limit (int, default: 2000 ) –

    The limit for how many characters should be included per yielded page.

  • line_limit (int, default: 25 ) –

    The limit for how many lines should be included per yielded page.

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

    A wrapper for each yielded page. This should leave "{}" in it to be replaced by the page's content.

Returns:

  • AsyncIterator[str] | Iterator[str] –

    An iterator of each page's content.

sync_paginate_string #

sync_paginate_string(lines, /, *, char_limit=2000, line_limit=25, wrapper=None)

Lazily paginate an iterator of lines.

Parameters:

  • lines (Iterable[str]) –

    The iterator of lines to paginate.

  • char_limit (int, default: 2000 ) –

    The limit for how many characters should be included per yielded page.

  • line_limit (int, default: 25 ) –

    The limit for how many lines should be included per yielded page.

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

    A wrapper for each yielded page. This should leave "{}" in it to be replaced by the page's content.

Returns:

  • Iterator[str] –

    An iterator of each page's content.