Client API Reference#

GatewayBotLike #

Bases: hikari.RESTAware, hikari.EventManagerAware, t.Protocol

A type that implements both RESTAware and EventManagerAware.

Client #

Client(
    app: GatewayBotLike | hikari.InteractionServerAware,
    *,
    ignore_unknown_interactions: bool = False,
    stop_bound_on_delete: bool = True,
    injector: alluka.abc.Client | None = None
)

The miru client.

It is responsible for handling component and modal interactions and dispatching them to the correct item handler.

PARAMETER	DESCRIPTION
`app`	The currently running app instance that will be used to receive interactions. TYPE: `GatewayBotLike \| hikari.InteractionServerAware`
`ignore_unknown_interactions`	Whether to ignore unknown interactions. If True, unknown interactions will be ignored and no warnings will be logged. TYPE: `bool` DEFAULT: `False`
`stop_bound_on_delete`	Whether to automatically stop bound views when the message it is bound to is deleted. This only applies to Gateway bots. When an app without EventManagerAware is used, this will be ignored. TYPE: `bool` DEFAULT: `True`
`injector`	The injector to use for dependency injection. If None, a new injector will be created. TYPE: `alluka.Client \| None` DEFAULT: `None`

app `property` #

app: hikari.RESTAware

The currently running app instance.

bot `property` #

bot: hikari.RESTAware

Alias for 'Client.app'. The currently running app instance.

rest `property` #

rest: hikari.api.RESTClient

The rest client instance of the underlying app.

event_manager `property` #

event_manager: hikari.api.EventManager

The event manager instance of the underlying app.

Warning

Accessing this property will raise a RuntimeError if the underlying app is not EventManagerAware.

cache `property` #

cache: hikari.api.Cache

The cache instance of the underlying app.

Warning

Accessing this property will raise a RuntimeError if the underlying app is not CacheAware.

interaction_server `property` #

interaction_server: hikari.api.InteractionServer

The interaction server instance of the underlying app.

Warning

Accessing this property will raise a RuntimeError if the underlying app is not InteractionServerAware.

is_rest `property` #

is_rest: bool

Whether the app is a rest client or a gateway client.

This controls the client response flow, if True, Client.handle_component_interaction and Client.handle_modal_interaction will return interaction response builders to be sent back to Discord, otherwise they will return None.

ignore_unknown_interactions `property` #

ignore_unknown_interactions: bool

Whether to ignore unknown interactions.

If True, unknown interactions will be ignored and no warnings will be logged.

injector `property` #

injector: alluka.abc.Client

The injector used for dependency injection.

from_arc `classmethod` #

from_arc(
    client: arc.abc.Client[t.Any],
    *,
    ignore_unknown_interactions: bool = False,
    stop_bound_on_delete: bool = True
) -> te.Self

Create a new client from an arc client, using it's dependency injector. This can be used to share dependencies between the arc client and the miru client.

PARAMETER	DESCRIPTION
`client`	The arc client to create the miru client from. TYPE: `arc.abc.Client[t.Any]`
`ignore_unknown_interactions`	Whether to ignore unknown interactions. If True, unknown interactions will be ignored and no warnings will be logged. TYPE: `bool` DEFAULT: `False`
`stop_bound_on_delete`	Whether to automatically stop bound views when the message it is bound to is deleted. This only applies to Gateway bots. When an app without EventManagerAware is used, this will be ignored. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Client`	The created client.

from_tanjun `classmethod` #

from_tanjun(
    client: tanjun.abc.Client,
    *,
    ignore_unknown_interactions: bool = False,
    stop_bound_on_delete: bool = True
) -> te.Self

Create a new client from a Tanjun client, using it's dependency injector. This can be used to share dependencies between the Tanjun client and the miru client.

Note

This convenience method only works if the Tanjun client was created with a bot object, not constructed manually.

PARAMETER	DESCRIPTION
`client`	The Tanjun client to create the miru client from. TYPE: `tanjun.Client`
`ignore_unknown_interactions`	Whether to ignore unknown interactions. If True, unknown interactions will be ignored and no warnings will be logged. TYPE: `bool` DEFAULT: `False`
`stop_bound_on_delete`	Whether to automatically stop bound views when the message it is bound to is deleted. This only applies to Gateway bots. When an app without EventManagerAware is used, this will be ignored. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Client`	The created client.

RAISES	DESCRIPTION
`RuntimeError`	If no `RESTAware` dependency was declared in the Tanjun client injector. Tanjun automatically sets this if the client was created with a bot object.
`RuntimeError`	If the located `RESTAware` dependency is not a valid application for miru. A valid application is either a `GatewayBotLike` or `InteractionServerAware`.

handle_component_interaction `async` #

handle_component_interaction(
    interaction: hikari.ComponentInteraction,
) -> ResponseBuildersT | None

Handle a component interaction.

PARAMETER	DESCRIPTION
`interaction`	The interaction to handle. TYPE: `hikari.ComponentInteraction`

RETURNS	DESCRIPTION
`ViewResponseBuildersT \| None`	If using a REST client, the response builders to send back to discord.

handle_modal_interaction `async` #

handle_modal_interaction(
    interaction: hikari.ModalInteraction,
) -> ModalResponseBuildersT | None

Handle a modal interaction.

PARAMETER	DESCRIPTION
`interaction`	The interaction to handle. TYPE: `hikari.ModalInteraction`

RETURNS	DESCRIPTION
`ModalResponseBuildersT \| None`	If using a REST client, the response builders to send back to discord.

clear #

clear() -> None

Stop all currently running views and modals.

get_bound_view #

get_bound_view(
    message: hikari.SnowflakeishOr[hikari.PartialMessage],
) -> View | None

Get a bound view that is currently managed by this client.

PARAMETER	DESCRIPTION
`message`	The message object or ID of the message that the view is bound to. TYPE: `hikari.SnowflakeishOr[hikari.PartialMessage]`

RETURNS	DESCRIPTION
`View \| None`	The view if found, otherwise None.

get_unbound_view #

get_unbound_view(custom_id: str) -> View | None

Get a currently running view that is managed by this client.

This will not return bound views.

PARAMETER	DESCRIPTION
`custom_id`	The custom_id of one of the view's children. TYPE: `str`

RETURNS	DESCRIPTION
`View[te.Self] \| None`	The view if found, otherwise None.

get_modal #

get_modal(custom_id: str) -> Modal | None

Get a currently running modal that is managed by this client.

PARAMETER	DESCRIPTION
`custom_id`	The custom_id of the modal. TYPE: `str`

RETURNS	DESCRIPTION
`Modal \| None`	The modal if found, otherwise None.

set_unhandled_component_interaction_hook #

set_unhandled_component_interaction_hook(
    hook: UnhandledCompInterHookT | None = None,
) -> (
    te.Self
    | t.Callable[[UnhandledCompInterHookT], te.Self]
)

Decorator to set the callback to be called for unhandled component interactions.

This will be called when a component interaction is received that is not handled by any of the currently running views.

PARAMETER	DESCRIPTION
`hook`	The function to set as the hook. TYPE: `UnhandledCompInterHookT` DEFAULT: `None`

RETURNS	DESCRIPTION
`te.Self`	The client for chaining calls.

Example

@client.set_unhandled_component_interaction_hook
async def unhandled_comp_hook(inter: hikari.ComponentInteraction) -> None:
    await inter.create_initial_response("❌ Something went wrong!")

Or, as a function:

client.set_unhandled_component_interaction_hook(unhandled_comp_hook)

set_unhandled_modal_interaction_hook #

set_unhandled_modal_interaction_hook(
    hook: UnhandledModalInterHookT | None = None,
) -> (
    te.Self
    | t.Callable[[UnhandledModalInterHookT], te.Self]
)

Decorator to set the callback to be called for unhandled modal interactions.

This will be called when a modal interaction is received that is not handled by any of the currently running modals.

PARAMETER	DESCRIPTION
`hook`	The function to set as the hook. TYPE: `UnhandledModalInterHookT` DEFAULT: `None`

RETURNS	DESCRIPTION
`te.Self`	The client for chaining calls.

Example

@client.set_unhandled_modal_interaction_hook
async def unhandled_modal_hook(inter: hikari.ModalInteraction) -> None:
    await inter.create_initial_response("❌ Something went wrong!")

Or, as a function:

client.set_unhandled_modal_interaction_hook(unhandled_modal_hook)

start_view #

start_view(
    view: View,
    *,
    bind_to: hikari.UndefinedNoneOr[
        hikari.SnowflakeishOr[hikari.PartialMessage]
    ] = hikari.UNDEFINED
) -> None

Add a view to this client and start it.

PARAMETER	DESCRIPTION
`view`	The view to start. TYPE: `View`
`bind_to`	The message to bind the view to. If set to `None`, the view will be unbound. If left as `UNDEFINED` (the default), the view will automatically be bound to the first message it receives an interaction from. TYPE: `hikari.UndefinedNoneOr[hikari.SnowflakeishOr[hikari.PartialMessage]]` DEFAULT: `hikari.UNDEFINED`

RAISES	DESCRIPTION
`ValueError`	If the view is not persistent and `bind_to` is set to None.
`!!! note`	A view can only be unbound if it is persistent, meaning that it has a timeout of None and all it's items have explicitly defined custom_ids. If a view is not persistent, it must be bound to a message.

start_modal #

start_modal(modal: Modal) -> None

Add a modal to this client and start it.

PARAMETER	DESCRIPTION
`modal`	The modal to start. TYPE: `Modal`

get_type_dependency #

get_type_dependency(
    type_: type[T],
    *,
    default: T | hikari.UndefinedType = hikari.UNDEFINED
) -> T

Get a type dependency for this client.

PARAMETER	DESCRIPTION
`type_`	The type of the dependency. TYPE: `type[T]`
`default`	The default value to return if the dependency does not exist. If not specified, a `KeyError` will be raised. TYPE: `T \| None` DEFAULT: `hikari.UNDEFINED`

RETURNS	DESCRIPTION
`T`	The instance of the dependency, or the default value if it does not exist.

RAISES	DESCRIPTION
`KeyError`	If the dependency does not exist and no default was specified.

set_type_dependency #

set_type_dependency(
    type_: type[T], instance: T
) -> te.Self

Set a type dependency for this client. This can then be injected into miru callbacks.

PARAMETER	DESCRIPTION
`type_`	The type of the dependency. TYPE: `type[T]`
`instance`	The instance of the dependency. TYPE: `T`

RETURNS	DESCRIPTION
`te.Self`	The client for chaining calls.

Example

class Counter:
    def __init__(self, value: int = 0) -> None:
        self.value = value

client.set_type_dependency(Counter, Counter(0))


class SomeView(miru.View):
    @miru.button(label="Counter!", style=hikari.ButtonStyle.PRIMARY)
    @client.inject_dependencies
    async def counter_button(
        self,
        ctx: miru.ViewContext,
        button: miru.Button,
        counter: Counter = miru.inject(),
    ) -> None:
        counter.value += 1
        await ctx.respond(f"Counter is {counter.value}")

inject_dependencies #

inject_dependencies(
    func: t.Callable[P, T] | None = None
) -> (
    t.Callable[P, T]
    | t.Callable[
        [t.Callable[P, T]], t.Callable[P, T]
    ]
)

Decorator to inject dependencies into the decorated function.

This should be the first (the one at the bottom) decorator of the given function.

Example

class Counter:
    def __init__(self, value: int = 0) -> None:
        self.value = value

client.set_type_dependency(Counter, Counter(0))


class SomeView(miru.View):
    @miru.button(label="Counter!", style=hikari.ButtonStyle.PRIMARY)
    @client.inject_dependencies
    async def counter_button(
        self,
        ctx: miru.ViewContext,
        button: miru.Button,
        counter: Counter = miru.inject(),
    ) -> None:
        counter.value += 1
        await ctx.respond(f"Counter is {counter.value}")

Client API Reference#

GatewayBotLike #

Client #

app property #

bot property #

rest property #

event_manager property #

cache property #

interaction_server property #

is_rest property #

ignore_unknown_interactions property #

injector property #

from_arc classmethod #

from_tanjun classmethod #

handle_component_interaction async #

handle_modal_interaction async #

clear #

get_bound_view #

get_unbound_view #

get_modal #

set_unhandled_component_interaction_hook #

set_unhandled_modal_interaction_hook #

start_view #

start_modal #

get_type_dependency #

set_type_dependency #

inject_dependencies #

app `property` #

bot `property` #

rest `property` #

event_manager `property` #

cache `property` #

interaction_server `property` #

is_rest `property` #

ignore_unknown_interactions `property` #

injector `property` #

from_arc `classmethod` #

from_tanjun `classmethod` #

handle_component_interaction `async` #

handle_modal_interaction `async` #