Item Handler API Reference#

class miru.abc.item_handler.ItemArranger[source]#

Bases: Generic[ItemT]

Calculate the position of an item based on it’s width, and automatically arrange items if no explicit row is specified.

Used internally by ItemHandler.

add_item(item: ItemT) → None[source]#

Add an item to the weights.

Parameters:

item (ItemT) – The item to add.

Raises:

RowFullError – The item does not fit on the row specified. This error is only raised if a row is specified explicitly.
HandlerFullError – The item does not fit on any row.

clear() → None[source]#: Clear the weights, remove all items.

remove_item(item: ItemT) → None[source]#

Remove an item from the weights.

Parameters:: item (ItemT) – The item to remove.

class miru.abc.item_handler.ItemHandler(*, timeout: float | int | timedelta | None = 120.0)[source]#

Bases: Sequence, ABC, Generic[BuilderT, ContextT, ItemT]

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

Parameters:

timeout (Optional[Union[float, int, datetime.timedelta]], optional) – The duration after which the item handler times out, in seconds, by default 120.0

Raises:

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

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

Adds a new item to the item handler.

Parameters:

item (Item[Any]) – The item to be added.

Raises:

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:

The item handler the item was added to.

Return type:

ItemHandler

build() → Sequence[BuilderT][source]#

Creates the action rows the item handler represents.

Returns:: 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.
Return type:: List[hikari.impl.MessageActionRowBuilder]

clear_items() → te.Self[source]#

Removes all items from this item handler.

Returns:: The item handler items were cleared from.
Return type:: ItemHandler

get_item_by(predicate: Callable[[ItemT], bool]) → ItemT | None[source]#

Get the first item that matches the given predicate.

Parameters:: predicate (Callable[[Item[Any]], bool]) – A predicate to match the item.
Returns:: The item that matched the predicate or None.
Return type:: Optional[Item[Any]]

get_item_by_id(custom_id: str) → ItemT | None[source]#

Get the first item that matches the given custom ID.

Parameters:: custom_id (str) – The custom_id of the component.
Returns:: The item that matched the custom ID or None.
Return type:: Optional[Item[Any]]

async on_timeout() → None[source]#: Called when the item handler times out. Override for custom timeout logic.

remove_item(item: ItemT) → te.Self[source]#

Removes the specified item from the item handler.

Parameters:: item (Item[Any]) – The item to be removed.
Returns:: The item handler the item was removed from.
Return type:: ItemHandler

stop() → None[source]#: Stop listening for interactions.

async wait(timeout: float | None = None) → None[source]#

Wait until the item handler has stopped receiving interactions.

Parameters:: timeout (Optional[float], optional) – The amount of time to wait, in seconds, by default None

property app: MiruAware#: The application that loaded the miru extension.

property bot: MiruAware#: The application that loaded the miru extension.

property children: Sequence[ItemT]#: A list of all items attached to the item handler.

property last_context: ContextT | None#: The last context that was received by the item handler.

property timeout: float | None#: The amount of time the item handler is allowed to idle for, in seconds. Must be None for persistent views.