Plugin#

GatewayPluginBase #

GatewayPluginBase(
    name: str,
    *,
    default_enabled_guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autodefer: bool | AutodeferMode | UndefinedType = hikari.UNDEFINED,
    is_dm_enabled: bool | UndefinedType = hikari.UNDEFINED,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool | UndefinedType = hikari.UNDEFINED
)

Bases: PluginBase[GatewayClientT]

The default implementation of a gateway plugin. To use this with the default GatewayClient implementation, see GatewayPlugin.

Note

Parameters left as hikari.UNDEFINED will be inherited from the parent client.

PARAMETER	DESCRIPTION
`name`	The name of this plugin. This must be unique across all plugins. TYPE: `str`
`default_enabled_guilds`	The default guilds to enable commands in TYPE: `Sequence[Snowflake] \| UndefinedType` DEFAULT: `UNDEFINED`
`autodefer`	If True, all commands in this plugin will automatically defer if it is taking longer than 2 seconds to respond. This can be overridden on a per-command basis. TYPE: `bool \| AutodeferMode` DEFAULT: `UNDEFINED`
`is_dm_enabled`	Whether commands in this plugin are enabled in DMs This can be overridden on a per-command basis. TYPE: `bool \| UndefinedType` DEFAULT: `UNDEFINED`
`default_permissions`	The default permissions for this plugin This can be overridden on a per-command basis. TYPE: `Permissions \| UndefinedType` DEFAULT: `UNDEFINED`
`is_nsfw`	Whether this plugin is only usable in NSFW channels TYPE: `bool \| UndefinedType` DEFAULT: `UNDEFINED`

Example

plugin = arc.GatewayPlugin("MyPlugin")

@plugin.include
@arc.slash_command("ping", "Ping the bot.")
async def ping(ctx: arc.GatewayContext) -> None:
    ...

# Snip

client.add_plugin(plugin)

client `property` #

client: ClientT

The client this plugin is included in.

concurrency_limiter `property` `writable` #

concurrency_limiter: ConcurrencyLimiterProto[ClientT] | None

The concurrency limiter for this plugin.

default_enabled_guilds `property` #

default_enabled_guilds: Sequence[Snowflake] | UndefinedType

The default guilds to enable commands in.

error_handler `property` `writable` #

error_handler: ErrorHandlerCallbackT[ClientT] | None

The error handler for this plugin.

hooks `property` #

hooks: MutableSequence[HookT[ClientT]]

The pre-execution hooks for this plugin.

is_rest `property` #

is_rest: bool

Whether or not this plugin is a REST plugin.

name `property` #

name: str

The name of this plugin.

post_hooks `property` #

post_hooks: MutableSequence[PostHookT[ClientT]]

The post-execution hooks for this plugin.

add_hook #

add_hook(hook: HookT[ClientT]) -> Self

Add a new pre-execution hook to this object.

Any function that takes a Context as its sole parameter and returns either a HookResult or None can be used as a hook.

PARAMETER	DESCRIPTION
`hook`	The hook to add. TYPE: `HookT[ClientT]`

RETURNS	DESCRIPTION
`Self`	This object for chaining.

add_post_hook #

add_post_hook(hook: PostHookT[ClientT]) -> Self

Add a new post-execution hook to this object.

Any function that takes a Context as its sole parameter and returns None can be used as a post-hook.

PARAMETER	DESCRIPTION
`hook`	The post-execution hook to add. TYPE: `PostHookT[ClientT]`

RETURNS	DESCRIPTION
`Self`	This object for chaining.

include #

include(command: CallableCommandBase[ClientT, BuilderT] | None = None) -> (
    CallableCommandBase[ClientT, BuilderT]
    | Callable[
        [CallableCommandBase[ClientT, BuilderT]],
        CallableCommandBase[ClientT, BuilderT],
    ]
)

Add a command to this plugin.

Note

This should be the last (topmost) decorator on a command.

PARAMETER	DESCRIPTION
`command`	The command to include in this plugin. TYPE: `CommandBase[ClientT, BuilderT]` DEFAULT: `None`

RAISES	DESCRIPTION
`RuntimeError`	If the command is already included in this plugin.

include_slash_group #

include_slash_group(
    name: str,
    description: str = "No description provided.",
    *,
    guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autodefer: bool | AutodeferMode | UndefinedType = hikari.UNDEFINED,
    is_dm_enabled: bool | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool | UndefinedType = hikari.UNDEFINED,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None,
    description_localizations: Mapping[Locale, str] | None = None
) -> SlashGroup[ClientT]

Add a new slash command group to this client.

PARAMETER	DESCRIPTION
`name`	The name of the slash command group. TYPE: `str`
`description`	The description of the slash command group. TYPE: `str` DEFAULT: `'No description provided.'`
`guilds`	The guilds to register the slash command group in TYPE: `Sequence[Snowflake] \| UndefinedType` DEFAULT: `UNDEFINED`
`autodefer`	If True, all commands in this group will automatically defer if it is taking longer than 2 seconds to respond. This can be overridden on a per-subcommand basis. TYPE: `bool \| AutodeferMode` DEFAULT: `UNDEFINED`
`is_dm_enabled`	Whether the slash command group is enabled in DMs TYPE: `bool` DEFAULT: `UNDEFINED`
`default_permissions`	The default permissions for the slash command group TYPE: `Permissions \| UndefinedType` DEFAULT: `UNDEFINED`
`name_localizations`	The name of the slash command group in different locales TYPE: `dict[Locale, str]` DEFAULT: `None`
`description_localizations`	The description of the slash command group in different locales TYPE: `dict[Locale, str]` DEFAULT: `None`
`is_nsfw`	Whether the slash command group is only usable in NSFW channels TYPE: `bool` DEFAULT: `UNDEFINED`

RETURNS	DESCRIPTION
`SlashGroup[Self]`	The slash command group that was created.
`!!! note`	Parameters left as `hikari.UNDEFINED` will be inherited from the parent plugin or client.

Example

group = client.include_slash_group("Group", "A group of commands.")

@group.include
@arc.slash_subcommand(name="Command", description="A command.")
async def cmd(ctx: arc.GatewayContext) -> None:
    await ctx.respond("Hello!")

inject_dependencies #

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

First order decorator to inject dependencies into the decorated function.

Warning

This makes functions uncallable if the plugin is not added to a client.

Note

Command callbacks are automatically injected with dependencies, thus this decorator is not needed for them.

Example

class MyDependency:
    def __init__(self, value: str):
        self.value = value

client = arc.GatewayClient(...)
client.set_type_dependency(MyDependency, MyDependency("Hello!"))
client.load_extension("foo")

# In 'foo':

plugin = arc.GatewayPlugin("My Plugin")

@plugin.inject_dependencies
def my_func(dep: MyDependency = arc.inject()) -> None:
    print(dep.value) # Prints "Hello!"

@arc.loader
def load(client: arc.GatewayClient) -> None:
    client.add_plugin(plugin)

See Also

Client.set_type_dependency A method to set dependencies for the client.

listen #

listen(
    *event_types: type[EventT],
) -> Callable[[EventCallbackT[EventT]], EventCallbackT[EventT]]

Generate a decorator to subscribe a callback to an event type.

This is a second-order decorator.

PARAMETER	DESCRIPTION
`*event_types`	The event types to subscribe to. If not provided, the event type will be inferred instead from the type hints on the function signature. `EventT` must be a subclass of `hikari.events.base_events.Event`. TYPE: `type[EventT]` DEFAULT: `()`

RETURNS	DESCRIPTION
`Callable[[EventT], EventT]`	A decorator for a coroutine function that passes it to `EventManager.subscribe` before returning the function reference.

set_concurrency_limiter #

set_concurrency_limiter(limiter: ConcurrencyLimiterProto[ClientT]) -> Self

Set the concurrency limiter for this object.

set_error_handler #

set_error_handler(
    callback: ErrorHandlerCallbackT[ClientT] | None = None,
) -> (
    ErrorHandlerCallbackT[ClientT]
    | Callable[[ErrorHandlerCallbackT[ClientT]], ErrorHandlerCallbackT[ClientT]]
)

Decorator to set an error handler for this object. This can be added to commands, groups, or plugins.

This function will be called when an exception is raised during the invocation of a command.

Example

@client.include
@arc.slash_command("foo", "Foo command description")
async def foo(ctx: arc.GatewayContext) -> None:
    raise RuntimeError("foo")

@foo.set_error_handler
async def foo_error_handler(ctx: arc.GatewayContext, exc: Exception) -> None:
    if isinstance(exc, RuntimeError):
        await ctx.respond("foo failed")
        return

    raise exc

Warning

Errors that cannot be handled by the error handler should be re-raised. Otherwise they will not propagate to the next error handler.

subscribe #

subscribe(event: type[Event], callback: EventCallbackT[Any]) -> None

Subscribe to an event.

PARAMETER	DESCRIPTION
`event`	The event to subscribe to. TYPE: `type[Event]`
`callback`	The callback to call when the event is dispatched. TYPE: `Callable[[EventT], Awaitable[None]]`

unsubscribe #

unsubscribe(event: type[Event], callback: EventCallbackT[Any]) -> None

Unsubscribe from an event.

PARAMETER	DESCRIPTION
`event`	The event to unsubscribe from. TYPE: `type[Event]`
`callback`	The callback to unsubscribe. TYPE: `Callable[[EventT], Awaitable[None]]`

walk_commands #

walk_commands(
    command_type: CommandType, *, callable_only: bool = False
) -> Iterator[Any]

Iterate over all commands of a certain type added to this plugin.

PARAMETER	DESCRIPTION
`command_type`	The type of commands to return. TYPE: `CommandType`
`callable_only`	Whether to only return commands that are directly callable. If True, command groups and subgroups will be skipped. TYPE: `bool` DEFAULT: `False`

YIELDS	DESCRIPTION
`CommandT[ClientT]`	The next command that matches the given criteria.

Example

for cmd in plugin.walk_commands(hikari.CommandType.SLASH):
    print(cmd.name)

Tip

To iterate over all types of commands, you may use itertools.chain():

import itertools

for cmd in itertools.chain(
    plugin.walk_commands(hikari.CommandType.SLASH),
    plugin.walk_commands(hikari.CommandType.MESSAGE),
    plugin.walk_commands(hikari.CommandType.USER),
):
    print(cmd.name)

RESTPluginBase #

RESTPluginBase(
    name: str,
    *,
    default_enabled_guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autodefer: bool | AutodeferMode | UndefinedType = hikari.UNDEFINED,
    is_dm_enabled: bool | UndefinedType = hikari.UNDEFINED,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool | UndefinedType = hikari.UNDEFINED
)

Bases: PluginBase[RESTClientT]

The default implementation of a REST plugin. To use this with the default RESTClient implementation, see RESTPlugin.

Note

Parameters left as hikari.UNDEFINED will be inherited from the parent client.

PARAMETER	DESCRIPTION
`name`	The name of this plugin. This must be unique across all plugins. TYPE: `str`
`default_enabled_guilds`	The default guilds to enable commands in TYPE: `Sequence[Snowflake] \| UndefinedType` DEFAULT: `UNDEFINED`
`autodefer`	If True, all commands in this plugin will automatically defer if it is taking longer than 2 seconds to respond. This can be overridden on a per-command basis. TYPE: `bool \| AutodeferMode` DEFAULT: `UNDEFINED`
`is_dm_enabled`	Whether commands in this plugin are enabled in DMs This can be overridden on a per-command basis. TYPE: `bool \| UndefinedType` DEFAULT: `UNDEFINED`
`default_permissions`	The default permissions for this plugin This can be overridden on a per-command basis. TYPE: `Permissions \| UndefinedType` DEFAULT: `UNDEFINED`
`is_nsfw`	Whether this plugin is only usable in NSFW channels TYPE: `bool \| UndefinedType` DEFAULT: `UNDEFINED`

Example

plugin = arc.RESTPlugin("MyPlugin")

@plugin.include
@arc.slash_command("ping", "Ping the bot.")
async def ping(ctx: arc.RESTContext) -> None:
    ...

# Snip

client.add_plugin(plugin)

client `property` #

client: ClientT

The client this plugin is included in.

concurrency_limiter `property` `writable` #

concurrency_limiter: ConcurrencyLimiterProto[ClientT] | None

The concurrency limiter for this plugin.

default_enabled_guilds `property` #

default_enabled_guilds: Sequence[Snowflake] | UndefinedType

The default guilds to enable commands in.

error_handler `property` `writable` #

error_handler: ErrorHandlerCallbackT[ClientT] | None

The error handler for this plugin.

hooks `property` #

hooks: MutableSequence[HookT[ClientT]]

The pre-execution hooks for this plugin.

is_rest `property` #

is_rest: bool

Whether or not this plugin is a REST plugin.

name `property` #

name: str

The name of this plugin.

post_hooks `property` #

post_hooks: MutableSequence[PostHookT[ClientT]]

The post-execution hooks for this plugin.

add_hook #

add_hook(hook: HookT[ClientT]) -> Self

Add a new pre-execution hook to this object.

Any function that takes a Context as its sole parameter and returns either a HookResult or None can be used as a hook.

PARAMETER	DESCRIPTION
`hook`	The hook to add. TYPE: `HookT[ClientT]`

RETURNS	DESCRIPTION
`Self`	This object for chaining.

add_post_hook #

add_post_hook(hook: PostHookT[ClientT]) -> Self

Add a new post-execution hook to this object.

Any function that takes a Context as its sole parameter and returns None can be used as a post-hook.

PARAMETER	DESCRIPTION
`hook`	The post-execution hook to add. TYPE: `PostHookT[ClientT]`

RETURNS	DESCRIPTION
`Self`	This object for chaining.

include #

include(command: CallableCommandBase[ClientT, BuilderT] | None = None) -> (
    CallableCommandBase[ClientT, BuilderT]
    | Callable[
        [CallableCommandBase[ClientT, BuilderT]],
        CallableCommandBase[ClientT, BuilderT],
    ]
)

Add a command to this plugin.

Note

This should be the last (topmost) decorator on a command.

PARAMETER	DESCRIPTION
`command`	The command to include in this plugin. TYPE: `CommandBase[ClientT, BuilderT]` DEFAULT: `None`

RAISES	DESCRIPTION
`RuntimeError`	If the command is already included in this plugin.

include_slash_group #

include_slash_group(
    name: str,
    description: str = "No description provided.",
    *,
    guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autodefer: bool | AutodeferMode | UndefinedType = hikari.UNDEFINED,
    is_dm_enabled: bool | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool | UndefinedType = hikari.UNDEFINED,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None,
    description_localizations: Mapping[Locale, str] | None = None
) -> SlashGroup[ClientT]

Add a new slash command group to this client.

PARAMETER	DESCRIPTION
`name`	The name of the slash command group. TYPE: `str`
`description`	The description of the slash command group. TYPE: `str` DEFAULT: `'No description provided.'`
`guilds`	The guilds to register the slash command group in TYPE: `Sequence[Snowflake] \| UndefinedType` DEFAULT: `UNDEFINED`
`autodefer`	If True, all commands in this group will automatically defer if it is taking longer than 2 seconds to respond. This can be overridden on a per-subcommand basis. TYPE: `bool \| AutodeferMode` DEFAULT: `UNDEFINED`
`is_dm_enabled`	Whether the slash command group is enabled in DMs TYPE: `bool` DEFAULT: `UNDEFINED`
`default_permissions`	The default permissions for the slash command group TYPE: `Permissions \| UndefinedType` DEFAULT: `UNDEFINED`
`name_localizations`	The name of the slash command group in different locales TYPE: `dict[Locale, str]` DEFAULT: `None`
`description_localizations`	The description of the slash command group in different locales TYPE: `dict[Locale, str]` DEFAULT: `None`
`is_nsfw`	Whether the slash command group is only usable in NSFW channels TYPE: `bool` DEFAULT: `UNDEFINED`

RETURNS	DESCRIPTION
`SlashGroup[Self]`	The slash command group that was created.
`!!! note`	Parameters left as `hikari.UNDEFINED` will be inherited from the parent plugin or client.

Example

group = client.include_slash_group("Group", "A group of commands.")

@group.include
@arc.slash_subcommand(name="Command", description="A command.")
async def cmd(ctx: arc.GatewayContext) -> None:
    await ctx.respond("Hello!")

inject_dependencies #

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

First order decorator to inject dependencies into the decorated function.

Warning

This makes functions uncallable if the plugin is not added to a client.

Note

Command callbacks are automatically injected with dependencies, thus this decorator is not needed for them.

Example

class MyDependency:
    def __init__(self, value: str):
        self.value = value

client = arc.GatewayClient(...)
client.set_type_dependency(MyDependency, MyDependency("Hello!"))
client.load_extension("foo")

# In 'foo':

plugin = arc.GatewayPlugin("My Plugin")

@plugin.inject_dependencies
def my_func(dep: MyDependency = arc.inject()) -> None:
    print(dep.value) # Prints "Hello!"

@arc.loader
def load(client: arc.GatewayClient) -> None:
    client.add_plugin(plugin)

See Also

Client.set_type_dependency A method to set dependencies for the client.

set_concurrency_limiter #

set_concurrency_limiter(limiter: ConcurrencyLimiterProto[ClientT]) -> Self

Set the concurrency limiter for this object.

set_error_handler #

set_error_handler(
    callback: ErrorHandlerCallbackT[ClientT] | None = None,
) -> (
    ErrorHandlerCallbackT[ClientT]
    | Callable[[ErrorHandlerCallbackT[ClientT]], ErrorHandlerCallbackT[ClientT]]
)

Decorator to set an error handler for this object. This can be added to commands, groups, or plugins.

This function will be called when an exception is raised during the invocation of a command.

Example

@client.include
@arc.slash_command("foo", "Foo command description")
async def foo(ctx: arc.GatewayContext) -> None:
    raise RuntimeError("foo")

@foo.set_error_handler
async def foo_error_handler(ctx: arc.GatewayContext, exc: Exception) -> None:
    if isinstance(exc, RuntimeError):
        await ctx.respond("foo failed")
        return

    raise exc

Warning

Errors that cannot be handled by the error handler should be re-raised. Otherwise they will not propagate to the next error handler.

walk_commands #

walk_commands(
    command_type: CommandType, *, callable_only: bool = False
) -> Iterator[Any]

Iterate over all commands of a certain type added to this plugin.

PARAMETER	DESCRIPTION
`command_type`	The type of commands to return. TYPE: `CommandType`
`callable_only`	Whether to only return commands that are directly callable. If True, command groups and subgroups will be skipped. TYPE: `bool` DEFAULT: `False`

YIELDS	DESCRIPTION
`CommandT[ClientT]`	The next command that matches the given criteria.

Example

for cmd in plugin.walk_commands(hikari.CommandType.SLASH):
    print(cmd.name)

Tip

To iterate over all types of commands, you may use itertools.chain():

import itertools

for cmd in itertools.chain(
    plugin.walk_commands(hikari.CommandType.SLASH),
    plugin.walk_commands(hikari.CommandType.MESSAGE),
    plugin.walk_commands(hikari.CommandType.USER),
):
    print(cmd.name)

Loading plugins from other files#

loader #

loader(
    callback: Callable[[ClientT], None] | None = None
) -> (
    Callable[[ClientT], None]
    | Callable[[Callable[[ClientT], None]], Callable[[ClientT], None]]
)

Decorator to set the load callback for this module.

Example

client.load_extension("my_extension")

# In my_extension.py:

@arc.loader
def load(client: arc.GatewayClient) -> None:
    client.add_plugin(...)

See Also

Client.load_extension

unloader #

unloader(
    callback: Callable[[ClientT], None] | None = None
) -> (
    Callable[[ClientT], None]
    | Callable[[Callable[[ClientT], None]], Callable[[ClientT], None]]
)

Decorator to set the unload callback for this module.

Example

client.unload_extension("my_extension")

# In my_extension.py:

@arc.unloader
def unload(client: arc.GatewayClient) -> None:
    client.remove_plugin(...)

See Also

Client.unload_extension

Plugin#

GatewayPluginBase #

client property #

concurrency_limiter property writable #

default_enabled_guilds property #

error_handler property writable #

hooks property #

is_rest property #

name property #

post_hooks property #

add_hook #

add_post_hook #

include #

include_slash_group #

inject_dependencies #

listen #

set_concurrency_limiter #

set_error_handler #

subscribe #

unsubscribe #

walk_commands #

RESTPluginBase #

client property #

concurrency_limiter property writable #

default_enabled_guilds property #

error_handler property writable #

hooks property #

is_rest property #

name property #

post_hooks property #

add_hook #

add_post_hook #

include #

include_slash_group #

inject_dependencies #

set_concurrency_limiter #

set_error_handler #

walk_commands #

Loading plugins from other files#

loader #

unloader #

client `property` #

concurrency_limiter `property` `writable` #

default_enabled_guilds `property` #

error_handler `property` `writable` #

hooks `property` #

is_rest `property` #

name `property` #

post_hooks `property` #

client `property` #

concurrency_limiter `property` `writable` #

default_enabled_guilds `property` #

error_handler `property` `writable` #

hooks `property` #

is_rest `property` #

name `property` #

post_hooks `property` #