Item Handler API Reference#

ItemHandler #

ItemHandler(
    *,
    timeout: float | int | datetime.timedelta | None = 120.0
)

Bases: Sequence[BuilderT], abc.ABC, t.Generic[BuilderT, RespBuilderT, ContextT, InteractionT, ItemT]

Abstract base class all item-handlers (e.g. views, modals) inherit from.

PARAMETER	DESCRIPTION
`timeout`	The duration after which the item handler times out, in seconds TYPE: `Optional[Union[float, int, datetime.timedelta]]` DEFAULT: `120.0`

RAISES	DESCRIPTION
`HandlerFullError`	Raised if the item handler has more than 25 components attached.

children `property` #

children: t.Sequence[ItemT]

A list of all items attached to the item handler.

timeout `property` #

timeout: float | None

The amount of time the item handler is allowed to idle for, in seconds. Must be None for persistent views.

client `property` #

client: Client

The client that started this handler.

last_context `property` #

last_context: ContextT | None

The last context that was received by the item handler.

add_item #

add_item(item: ItemT) -> te.Self

Adds a new item to the item handler.

PARAMETER	DESCRIPTION
`item`	The item to be added. TYPE: `Item[Any]`

RAISES	DESCRIPTION
`ValueError`	ItemHandler already has 25 components attached.
`TypeError`	Parameter item is not an instance of Item.
`ItemAlreadyAttachedError`	The item is already attached to this item handler.
`ItemAlreadyAttachedError`	The item is already attached to another item handler.

RETURNS	DESCRIPTION
`ItemHandler`	The item handler the item was added to.

remove_item #

remove_item(item: ItemT) -> te.Self

Removes the specified item from the item handler.

PARAMETER	DESCRIPTION
`item`	The item to be removed. TYPE: `Item[Any]`

RETURNS	DESCRIPTION
`ItemHandler`	The item handler the item was removed from.

clear_items #

clear_items() -> te.Self

Removes all items from this item handler.

RETURNS	DESCRIPTION
`ItemHandler`	The item handler items were cleared from.

get_item_by #

get_item_by(
    predicate: t.Callable[[ItemT], bool],
    *,
    default: T | hikari.UndefinedType = hikari.UNDEFINED
) -> ItemT | T

Get the first item that matches the given predicate.

PARAMETER	DESCRIPTION
`predicate`	A predicate to match the item. TYPE: `Callable[[Item[Any]], bool]`
`default`	The default value to return if the item doesn't exist. TYPE: `T` DEFAULT: `hikari.UNDEFINED`

RETURNS	DESCRIPTION
`ItemT \| T`	The item that matched the predicate or default.

RAISES	DESCRIPTION
`KeyError`	No item that matches predicate was found and no default was provided.

get_item_by_id #

get_item_by_id(
    custom_id: str,
    default: T | hikari.UndefinedType = hikari.UNDEFINED,
) -> ItemT | T

Get the first item that matches the given custom ID.

PARAMETER	DESCRIPTION
`custom_id`	The custom_id of the component. TYPE: `str`
`default`	The default value to return if the item doesn't exist. TYPE: `T` DEFAULT: `hikari.UNDEFINED`

RETURNS	DESCRIPTION
`ItemT \| T`	The item that matched the custom ID or the default.

RAISES	DESCRIPTION
`KeyError`	No item that matches the custom ID was found and no default was provided.

build #

build() -> t.Sequence[BuilderT]

Creates the action rows the item handler represents.

RETURNS	DESCRIPTION
`List[hikari.impl.MessageActionRowBuilder]`	A list of action rows containing all items attached to this item handler, converted to hikari component objects. If the item handler has no items attached, this returns an empty list.

on_timeout `async` #

on_timeout() -> None

Called when the item handler times out. Override for custom timeout logic.

stop #

stop() -> None

Stop listening for interactions.

wait `async` #

wait(timeout: float | None = None) -> None

Wait until the item handler has stopped receiving interactions.

PARAMETER	DESCRIPTION
`timeout`	The amount of time to wait, in seconds TYPE: `Optional[float]` DEFAULT: `None`