Client

GatewayContext module-attribute

GatewayContext = Context[GatewayClient]

A context using the default gateway client implementation. An alias for arc.Context[arc.GatewayClient].

GatewayPlugin module-attribute

GatewayPlugin = GatewayPluginBase[GatewayClient]

An alias for arc.GatewayPluginBase[arc.GatewayClient].

RESTContext module-attribute

RESTContext = Context[RESTClient]

A context using the default REST client implementation. An alias for arc.Context[arc.RESTClient].

RESTPlugin module-attribute

RESTPlugin = RESTPluginBase[RESTClient]

A plugin using the default REST client implementation. An alias for arc.RESTPluginBase[arc.RESTClient].

GatewayClient

GatewayClient(
    app: GatewayBotT,
    *,
    default_enabled_guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autosync: bool = True,
    autodefer: bool | AutodeferMode = True,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool = False,
    is_dm_enabled: bool = True,
    provided_locales: Sequence[Locale] | None = None,
    injector: Client | None = None
)

Bases: GatewayClientBase[GatewayBotAware]

The default gateway client implementation. Effectively an alias for arc.GatewayClientBase[hikari.GatewayBotAware].

If you want to use a RESTBot, use RESTClient instead.

PARAMETER	DESCRIPTION
app	The application this client is for. TYPE: GatewayBotAware
default_enabled_guilds	The guilds that commands will be registered in by default TYPE: Sequence[Snowflakeish] | None DEFAULT: UNDEFINED
autosync	Whether to automatically sync commands on startup TYPE: bool DEFAULT: True
autodefer	Whether to automatically defer responses This applies to all commands, and can be overridden on a per-command basis. TYPE: bool | AutodeferMode DEFAULT: True
default_permissions	The default permissions for commands This applies to all commands, and can be overridden on a per-command basis. TYPE: Permissions | UndefinedType DEFAULT: UNDEFINED
is_nsfw	Whether commands are NSFW This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: False
is_dm_enabled	Whether commands are enabled in DMs This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: True
provided_locales	The locales that will be provided to the client by locale provider callbacks TYPE: Sequence[Locale] | None DEFAULT: None
injector	If you already have an injector instance, you may pass it here. Otherwise, a new one will be created by default. TYPE: Client | None DEFAULT: None

Example

import hikari
import arc

bot = hikari.GatewayBot("TOKEN")
client = arc.GatewayClient(bot)

app property

app: AppT

The application this client is for.

application property

application: Application | None

The application object for this client. This is fetched on startup.

cache property

cache: Cache

The cache for this client.

concurrency_limiter property

concurrency_limiter: ConcurrencyLimiterProto[Self] | None

The concurrency limiter for this client.

default_enabled_guilds property

default_enabled_guilds: Sequence[Snowflake] | UndefinedType

The guilds that slash commands will be registered in by default.

error_handler property

error_handler: ErrorHandlerCallbackT[Self] | None

The error handler for this client.

hooks property

hooks: MutableSequence[HookT[Self]]

The pre-execution hooks for this client.

injector property

injector: Client

The injector for this client.

is_rest property

is_rest: bool

Whether this client is a REST client.

is_started property

is_started: bool

Whether the client has started up.

owner_ids property

owner_ids: Sequence[Snowflake]

The IDs of the owners of this application.

plugins property

plugins: Mapping[str, PluginBase[Self]]

The plugins added to this client.

post_hooks property

post_hooks: MutableSequence[PostHookT[Self]]

The post-execution hooks for this client.

rest property

rest: RESTClient

The REST client of the underyling app.

add_hook

add_hook(
    hook: HookT[Self] | None = None,
) -> Self | Callable[[HookT[Self]], HookT[Self]]

Add a pre-execution hook to this client. This hook will be executed before every command that is added to this client.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: HookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_post_hook

add_injection_hook

add_injection_hook(
    hook: InjectionHookT[Self] | None = None,
) -> Self | Callable[[InjectionHookT[Self]], InjectionHookT[Self]]

Add an injection hook to this client. This hook will be called when a command is called, and an OverridingContext is passed, allowing you to inject dependencies for the command call.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: InjectionHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_injection_hook
async def inject(ctx: arc.GatewayContext, inj_ctx: arc.InjectorOverridingContext) -> None:
    foo: MyType = example_data[ctx.guild_id]
    inj_ctx.set_type_dependency(MyType, foo)

See Also

• Client.set_type_dependency

add_plugin

add_plugin(plugin: PluginBase[Self]) -> Self

Add a plugin to this client.

PARAMETER	DESCRIPTION
plugin	The plugin to add. TYPE: Plugin[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

add_post_hook

add_post_hook(
    hook: PostHookT[Self] | None = None,
) -> Self | Callable[[PostHookT[Self]], PostHookT[Self]]

Add a post-execution hook to this client. This hook will be executed after every command that is added to this client.

Warning

Post-execution hooks will be called even if the command callback raises an exception.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: PostHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_hook

add_shutdown_hook

add_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a shutdown hook for this client.

This will be called when the client shuts down.

PARAMETER	DESCRIPTION
hook	The shutdown hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.add_shutdown_hook(shutdown_hook)

add_startup_hook

add_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a startup hook for this client.

This will be called when the client starts up.

PARAMETER	DESCRIPTION
hook	The startup hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.add_startup_hook(startup_hook)

create_task

create_task(coro: Coroutine[Any, Any, T]) -> Task[T]

Create a task and add it to the client's internal task set.

This can be used for "fire and forget" task creation.

PARAMETER	DESCRIPTION
coro	The coroutine to create a task for. TYPE: Coroutine[Any, Any, T]

RETURNS	DESCRIPTION
Task[T]	The created task.

get_type_dependency

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

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 provided, this will raise an exception if the dependency does not exist. TYPE: DefaultT DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
T | DefaultT	The instance of the dependency, if it exists, otherwise default.

RAISES	DESCRIPTION
KeyError	If the dependency does not exist and default was not provided.

include

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

Decorator to add a command to this client.

Note

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

PARAMETER	DESCRIPTION
command	The command to add. TYPE: CommandBase[Self, BuilderT] DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If the command is already added to a plugin.

Example

@client.include # Add the command to the client.
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext) -> None:
    ...

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,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None,
    description_localizations: Mapping[Locale, str] | None = None,
    is_nsfw: bool = False
) -> SlashGroup[Self]

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: False

RETURNS	DESCRIPTION
SlashGroup[Self]	The slash command group that was created.
!!! note	Parameters left as hikari.UNDEFINED will be inherited from the parent 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]]

Decorator to inject dependencies into the decorated function.

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.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.inject_dependencies
def my_func(dep: MyDependency = arc.inject()) -> None:
    print(dep.value)

my_func() # Prints "Hello!"

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
t.Callable[t.Callable[[EventT], t.Awaitable[None]]], t.Callable[[EventT], t.Awaitable[None]]]	A decorator for a coroutine function that passes it to EventManager.subscribe before returning the function reference.

load_extension

load_extension(path: str) -> Self

Load a python module with path path as an extension. This will import the module, and call it's loader function.

PARAMETER	DESCRIPTION
path	The path to the module to load. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the module does not have a loader.

Example

client = arc.GatewayClient(...)
client.load_extension("extension")

# In extension.py

plugin = arc.GatewayPlugin("test_plugin")

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

See Also

• @arc.loader
• Client.load_extensions_from
• Client.unload_extension

load_extensions_from

load_extensions_from(dir_path: str | Path, recursive: bool = False) -> Self

Load all python modules in a directory as extensions. This will import the modules, and call their loader functions.

PARAMETER	DESCRIPTION
dir_path	The path to the directory to load extensions from. TYPE: str
recursive	Whether to load extensions from subdirectories TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionLoadError	If dir_path does not exist or is not a directory.
ExtensionLoadError	If a module does not have a loader defined.

Example

client = arc.GatewayClient(...)
client.load_extensions_from("extensions/foo")

See Also

• @arc.loader
• Client.load_extension
• Client.unload_extension

on_autocomplete_interaction async

on_autocomplete_interaction(
    interaction: AutocompleteInteraction,
) -> InteractionAutocompleteBuilder | None

Should be called when an autocomplete interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: AutocompleteInteraction

RETURNS	DESCRIPTION
InteractionAutocompleteBuilder | None	The autocomplete builder to send back to Discord, if using a REST client.

on_command_interaction async

on_command_interaction(
    interaction: CommandInteraction,
) -> ResponseBuilderT | None

Should be called when a command interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: CommandInteraction

RETURNS	DESCRIPTION
ResponseBuilderT | None	The response builder to send back to Discord, if using a REST client.

purge_all_commands async

purge_all_commands(guild: SnowflakeishOr[PartialGuild] | None = None) -> None

Purge all commands registered on Discord. This can be used to clean up commands.

Warning

This will remove all commands registered on Discord, including commands not registered by this client.

PARAMETER	DESCRIPTION
guild	The guild to purge commands from If a guild is not provided, this will purge global commands. TYPE: SnowflakeishOr[PartialGuild] | None DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.purge_all_commands is called before Client.on_startup.

remove_injection_hook

remove_injection_hook(hook: InjectionHookT[Self]) -> Self

Remove an injection hook from this client.

PARAMETER	DESCRIPTION
hook	The hook to remove. TYPE: InjectionHookT[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the hook is not registered with this client.

remove_plugin

remove_plugin(plugin: str | PluginBase[Self]) -> Self

Remove a plugin from this client.

PARAMETER	DESCRIPTION
plugin	The plugin or name of the plugin to remove. TYPE: str | Plugin[Self]

RAISES	DESCRIPTION
ValueError	If there is no plugin with the given name.

RETURNS	DESCRIPTION
Self	The client for chaining calls.

resync_commands async

resync_commands() -> None

Synchronize the commands registered in this client with Discord.

Warning

Calling this is expensive, and should only be done when absolutely necessary. The client automatically syncs commands on startup, unless the autosync parameter is set to False when creating the client.

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.resync_commands is called before Client.on_startup.

set_command_locale_provider

set_command_locale_provider(
    provider: CommandLocaleRequestT | None = None,
) -> Self | Callable[[CommandLocaleRequestT], Self]

Decorator to set the command locale provider for this client.

This will be called for each command for each locale.

PARAMETER	DESCRIPTION
provider	The command locale provider to set. TYPE: CommandLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_command_locale_provider
def command_locale_provider(request: arc.CommandLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_command_locale_provider(command_locale_provider)

set_concurrency_limit

set_concurrency_limit(limiter: ConcurrencyLimiterProto[Self]) -> Self

Set the concurrency limiter for this client.

PARAMETER	DESCRIPTION
limiter	The concurrency limiter to set. TYPE: ConcurrencyLimiterProto[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

set_custom_locale_provider

set_custom_locale_provider(
    provider: CustomLocaleRequestT | None = None,
) -> Self | Callable[[CustomLocaleRequestT], Self]

Decorator to set the custom locale provider for this client.

This will be called for each custom locale request performed via Context.loc().

PARAMETER	DESCRIPTION
provider	The custom locale provider to set. TYPE: CustomLocaleRequestT DEFAULT: None

Example

@client.set_custom_locale_provider
def custom_locale_provider(request: arc.CustomLocaleRequest) -> str:
    ...

Or, as a function:

client.set_custom_locale_provider(custom_locale_provider)

set_error_handler

set_error_handler(
    handler: ErrorHandlerCallbackT[Self] | None = None,
) -> Self | Callable[[ErrorHandlerCallbackT[Self]], Self]

Decorator to set the error handler for this client.

This will be called when a command callback raises an exception that is not handled by any other error handlers.

PARAMETER	DESCRIPTION
handler	The error handler to set. TYPE: ErrorHandlerCallbackT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_error_handler
async def error_handler_func(ctx: arc.GatewayContext, exception: Exception) -> None:
    await ctx.respond(f"❌ Something went wrong: {exception}")

Warning

Errors that cannot be handled by the error handler should be re-raised. Otherwise tracebacks will not be printed to stderr.

Or, as a function:

client.set_error_handler(error_handler_func)

set_option_locale_provider

set_option_locale_provider(
    provider: OptionLocaleRequestT | None = None,
) -> Self | Callable[[OptionLocaleRequestT], Self]

Decorator to set the option locale provider for this client.

This will be called for each option of each command for each locale.

PARAMETER	DESCRIPTION
provider	The option locale provider to set. TYPE: OptionLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_option_locale_provider
def option_locale_provider(request: arc.OptionLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_option_locale_provider(option_locale_provider)

set_shutdown_hook

set_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the shutdown hook for this client.

This will be called when the client shuts down.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_shutdown_hook instead.

PARAMETER	DESCRIPTION
hook	The shutdown hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.set_shutdown_hook(shutdown_hook)

set_startup_hook

set_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the startup hook for this client.

This will be called when the client starts up.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_startup_hook instead.

PARAMETER	DESCRIPTION
hook	The startup hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.set_startup_hook(startup_hook)

set_type_dependency

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

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

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

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

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

client.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.include
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext, dep: MyDependency = arc.inject()) -> None:
    await ctx.respond(dep.value)

See Also

• Client.get_type_dependency A method to get dependencies for the client.

• Client.inject_dependencies A decorator to inject dependencies into arbitrary functions.

subscribe

subscribe(event_type: type[EventT], callback: EventCallbackT[EventT]) -> None

Subscribe to an event.

PARAMETER	DESCRIPTION
event_type	The event type to subscribe to. EventT must be a subclass of hikari.events.base_events.Event. TYPE: type[EventT]
callback	The callback to call when the event is dispatched. TYPE: t.Callable[EventT], t.Awaitable[None]]

unload_extension

unload_extension(path: str) -> Self

Unload a python module with path path as an extension.

PARAMETER	DESCRIPTION
path	The path to the module to unload. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionUnloadError	If the module does not have an unloader or is not loaded.

See Also

• Client.load_extension
• Client.load_extensions_from

unsubscribe

unsubscribe(event_type: type[EventT], callback: EventCallbackT[EventT]) -> None

Unsubscribe from an event.

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

wait_until_started async

wait_until_started() -> None

Wait until the client has started up.

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. This is only applicable to slash commands. TYPE: bool DEFAULT: False

YIELDS	DESCRIPTION
CommandT[Self]	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)

GatewayClientBase

GatewayClientBase(
    app: GatewayBotT,
    *,
    default_enabled_guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autosync: bool = True,
    autodefer: bool | AutodeferMode = True,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool = False,
    is_dm_enabled: bool = True,
    provided_locales: Sequence[Locale] | None = None,
    injector: Client | None = None
)

Bases: Client[GatewayBotT]

The base class for an arc client with Gateway support. This class primarily exists to allow for the creation of custom client types.

For the default implementation of a Gateway client, see GatewayClient.

PARAMETER	DESCRIPTION
app	The application this client is for. TYPE: GatewayBotAware
default_enabled_guilds	The guilds that commands will be registered in by default TYPE: Sequence[Snowflakeish] | None DEFAULT: UNDEFINED
autosync	Whether to automatically sync commands on startup TYPE: bool DEFAULT: True
autodefer	Whether to automatically defer responses This applies to all commands, and can be overridden on a per-command basis. TYPE: bool | AutodeferMode DEFAULT: True
default_permissions	The default permissions for commands This applies to all commands, and can be overridden on a per-command basis. TYPE: Permissions | UndefinedType DEFAULT: UNDEFINED
is_nsfw	Whether commands are NSFW This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: False
is_dm_enabled	Whether commands are enabled in DMs This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: True
provided_locales	The locales that will be provided to the client by locale provider callbacks TYPE: Sequence[Locale] | None DEFAULT: None
injector	If you already have an injector instance, you may pass it here. Otherwise, a new one will be created by default. TYPE: Client | None DEFAULT: None

app property

app: AppT

The application this client is for.

application property

application: Application | None

The application object for this client. This is fetched on startup.

cache property

cache: Cache

The cache for this client.

concurrency_limiter property

concurrency_limiter: ConcurrencyLimiterProto[Self] | None

The concurrency limiter for this client.

default_enabled_guilds property

default_enabled_guilds: Sequence[Snowflake] | UndefinedType

The guilds that slash commands will be registered in by default.

error_handler property

error_handler: ErrorHandlerCallbackT[Self] | None

The error handler for this client.

hooks property

hooks: MutableSequence[HookT[Self]]

The pre-execution hooks for this client.

injector property

injector: Client

The injector for this client.

is_rest property

is_rest: bool

Whether this client is a REST client.

is_started property

is_started: bool

Whether the client has started up.

owner_ids property

owner_ids: Sequence[Snowflake]

The IDs of the owners of this application.

plugins property

plugins: Mapping[str, PluginBase[Self]]

The plugins added to this client.

post_hooks property

post_hooks: MutableSequence[PostHookT[Self]]

The post-execution hooks for this client.

rest property

rest: RESTClient

The REST client of the underyling app.

add_hook

add_hook(
    hook: HookT[Self] | None = None,
) -> Self | Callable[[HookT[Self]], HookT[Self]]

Add a pre-execution hook to this client. This hook will be executed before every command that is added to this client.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: HookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_post_hook

add_injection_hook

add_injection_hook(
    hook: InjectionHookT[Self] | None = None,
) -> Self | Callable[[InjectionHookT[Self]], InjectionHookT[Self]]

Add an injection hook to this client. This hook will be called when a command is called, and an OverridingContext is passed, allowing you to inject dependencies for the command call.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: InjectionHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_injection_hook
async def inject(ctx: arc.GatewayContext, inj_ctx: arc.InjectorOverridingContext) -> None:
    foo: MyType = example_data[ctx.guild_id]
    inj_ctx.set_type_dependency(MyType, foo)

See Also

• Client.set_type_dependency

add_plugin

add_plugin(plugin: PluginBase[Self]) -> Self

Add a plugin to this client.

PARAMETER	DESCRIPTION
plugin	The plugin to add. TYPE: Plugin[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

add_post_hook

add_post_hook(
    hook: PostHookT[Self] | None = None,
) -> Self | Callable[[PostHookT[Self]], PostHookT[Self]]

Add a post-execution hook to this client. This hook will be executed after every command that is added to this client.

Warning

Post-execution hooks will be called even if the command callback raises an exception.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: PostHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_hook

add_shutdown_hook

add_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a shutdown hook for this client.

This will be called when the client shuts down.

PARAMETER	DESCRIPTION
hook	The shutdown hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.add_shutdown_hook(shutdown_hook)

add_startup_hook

add_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a startup hook for this client.

This will be called when the client starts up.

PARAMETER	DESCRIPTION
hook	The startup hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.add_startup_hook(startup_hook)

create_task

create_task(coro: Coroutine[Any, Any, T]) -> Task[T]

Create a task and add it to the client's internal task set.

This can be used for "fire and forget" task creation.

PARAMETER	DESCRIPTION
coro	The coroutine to create a task for. TYPE: Coroutine[Any, Any, T]

RETURNS	DESCRIPTION
Task[T]	The created task.

get_type_dependency

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

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 provided, this will raise an exception if the dependency does not exist. TYPE: DefaultT DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
T | DefaultT	The instance of the dependency, if it exists, otherwise default.

RAISES	DESCRIPTION
KeyError	If the dependency does not exist and default was not provided.

include

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

Decorator to add a command to this client.

Note

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

PARAMETER	DESCRIPTION
command	The command to add. TYPE: CommandBase[Self, BuilderT] DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If the command is already added to a plugin.

Example

@client.include # Add the command to the client.
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext) -> None:
    ...

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,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None,
    description_localizations: Mapping[Locale, str] | None = None,
    is_nsfw: bool = False
) -> SlashGroup[Self]

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: False

RETURNS	DESCRIPTION
SlashGroup[Self]	The slash command group that was created.
!!! note	Parameters left as hikari.UNDEFINED will be inherited from the parent 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]]

Decorator to inject dependencies into the decorated function.

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.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.inject_dependencies
def my_func(dep: MyDependency = arc.inject()) -> None:
    print(dep.value)

my_func() # Prints "Hello!"

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
t.Callable[t.Callable[[EventT], t.Awaitable[None]]], t.Callable[[EventT], t.Awaitable[None]]]	A decorator for a coroutine function that passes it to EventManager.subscribe before returning the function reference.

load_extension

load_extension(path: str) -> Self

Load a python module with path path as an extension. This will import the module, and call it's loader function.

PARAMETER	DESCRIPTION
path	The path to the module to load. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the module does not have a loader.

Example

client = arc.GatewayClient(...)
client.load_extension("extension")

# In extension.py

plugin = arc.GatewayPlugin("test_plugin")

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

See Also

• @arc.loader
• Client.load_extensions_from
• Client.unload_extension

load_extensions_from

load_extensions_from(dir_path: str | Path, recursive: bool = False) -> Self

Load all python modules in a directory as extensions. This will import the modules, and call their loader functions.

PARAMETER	DESCRIPTION
dir_path	The path to the directory to load extensions from. TYPE: str
recursive	Whether to load extensions from subdirectories TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionLoadError	If dir_path does not exist or is not a directory.
ExtensionLoadError	If a module does not have a loader defined.

Example

client = arc.GatewayClient(...)
client.load_extensions_from("extensions/foo")

See Also

• @arc.loader
• Client.load_extension
• Client.unload_extension

on_autocomplete_interaction async

on_autocomplete_interaction(
    interaction: AutocompleteInteraction,
) -> InteractionAutocompleteBuilder | None

Should be called when an autocomplete interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: AutocompleteInteraction

RETURNS	DESCRIPTION
InteractionAutocompleteBuilder | None	The autocomplete builder to send back to Discord, if using a REST client.

on_command_interaction async

on_command_interaction(
    interaction: CommandInteraction,
) -> ResponseBuilderT | None

Should be called when a command interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: CommandInteraction

RETURNS	DESCRIPTION
ResponseBuilderT | None	The response builder to send back to Discord, if using a REST client.

purge_all_commands async

purge_all_commands(guild: SnowflakeishOr[PartialGuild] | None = None) -> None

Purge all commands registered on Discord. This can be used to clean up commands.

Warning

This will remove all commands registered on Discord, including commands not registered by this client.

PARAMETER	DESCRIPTION
guild	The guild to purge commands from If a guild is not provided, this will purge global commands. TYPE: SnowflakeishOr[PartialGuild] | None DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.purge_all_commands is called before Client.on_startup.

remove_injection_hook

remove_injection_hook(hook: InjectionHookT[Self]) -> Self

Remove an injection hook from this client.

PARAMETER	DESCRIPTION
hook	The hook to remove. TYPE: InjectionHookT[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the hook is not registered with this client.

remove_plugin

remove_plugin(plugin: str | PluginBase[Self]) -> Self

Remove a plugin from this client.

PARAMETER	DESCRIPTION
plugin	The plugin or name of the plugin to remove. TYPE: str | Plugin[Self]

RAISES	DESCRIPTION
ValueError	If there is no plugin with the given name.

RETURNS	DESCRIPTION
Self	The client for chaining calls.

resync_commands async

resync_commands() -> None

Synchronize the commands registered in this client with Discord.

Warning

Calling this is expensive, and should only be done when absolutely necessary. The client automatically syncs commands on startup, unless the autosync parameter is set to False when creating the client.

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.resync_commands is called before Client.on_startup.

set_command_locale_provider

set_command_locale_provider(
    provider: CommandLocaleRequestT | None = None,
) -> Self | Callable[[CommandLocaleRequestT], Self]

Decorator to set the command locale provider for this client.

This will be called for each command for each locale.

PARAMETER	DESCRIPTION
provider	The command locale provider to set. TYPE: CommandLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_command_locale_provider
def command_locale_provider(request: arc.CommandLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_command_locale_provider(command_locale_provider)

set_concurrency_limit

set_concurrency_limit(limiter: ConcurrencyLimiterProto[Self]) -> Self

Set the concurrency limiter for this client.

PARAMETER	DESCRIPTION
limiter	The concurrency limiter to set. TYPE: ConcurrencyLimiterProto[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

set_custom_locale_provider

set_custom_locale_provider(
    provider: CustomLocaleRequestT | None = None,
) -> Self | Callable[[CustomLocaleRequestT], Self]

Decorator to set the custom locale provider for this client.

This will be called for each custom locale request performed via Context.loc().

PARAMETER	DESCRIPTION
provider	The custom locale provider to set. TYPE: CustomLocaleRequestT DEFAULT: None

Example

@client.set_custom_locale_provider
def custom_locale_provider(request: arc.CustomLocaleRequest) -> str:
    ...

Or, as a function:

client.set_custom_locale_provider(custom_locale_provider)

set_error_handler

set_error_handler(
    handler: ErrorHandlerCallbackT[Self] | None = None,
) -> Self | Callable[[ErrorHandlerCallbackT[Self]], Self]

Decorator to set the error handler for this client.

This will be called when a command callback raises an exception that is not handled by any other error handlers.

PARAMETER	DESCRIPTION
handler	The error handler to set. TYPE: ErrorHandlerCallbackT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_error_handler
async def error_handler_func(ctx: arc.GatewayContext, exception: Exception) -> None:
    await ctx.respond(f"❌ Something went wrong: {exception}")

Warning

Errors that cannot be handled by the error handler should be re-raised. Otherwise tracebacks will not be printed to stderr.

Or, as a function:

client.set_error_handler(error_handler_func)

set_option_locale_provider

set_option_locale_provider(
    provider: OptionLocaleRequestT | None = None,
) -> Self | Callable[[OptionLocaleRequestT], Self]

Decorator to set the option locale provider for this client.

This will be called for each option of each command for each locale.

PARAMETER	DESCRIPTION
provider	The option locale provider to set. TYPE: OptionLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_option_locale_provider
def option_locale_provider(request: arc.OptionLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_option_locale_provider(option_locale_provider)

set_shutdown_hook

set_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the shutdown hook for this client.

This will be called when the client shuts down.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_shutdown_hook instead.

PARAMETER	DESCRIPTION
hook	The shutdown hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.set_shutdown_hook(shutdown_hook)

set_startup_hook

set_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the startup hook for this client.

This will be called when the client starts up.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_startup_hook instead.

PARAMETER	DESCRIPTION
hook	The startup hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.set_startup_hook(startup_hook)

set_type_dependency

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

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

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

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

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

client.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.include
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext, dep: MyDependency = arc.inject()) -> None:
    await ctx.respond(dep.value)

See Also

• Client.get_type_dependency A method to get dependencies for the client.

• Client.inject_dependencies A decorator to inject dependencies into arbitrary functions.

subscribe

subscribe(event_type: type[EventT], callback: EventCallbackT[EventT]) -> None

Subscribe to an event.

PARAMETER	DESCRIPTION
event_type	The event type to subscribe to. EventT must be a subclass of hikari.events.base_events.Event. TYPE: type[EventT]
callback	The callback to call when the event is dispatched. TYPE: t.Callable[EventT], t.Awaitable[None]]

unload_extension

unload_extension(path: str) -> Self

Unload a python module with path path as an extension.

PARAMETER	DESCRIPTION
path	The path to the module to unload. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionUnloadError	If the module does not have an unloader or is not loaded.

See Also

• Client.load_extension
• Client.load_extensions_from

unsubscribe

unsubscribe(event_type: type[EventT], callback: EventCallbackT[EventT]) -> None

Unsubscribe from an event.

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

wait_until_started async

wait_until_started() -> None

Wait until the client has started up.

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. This is only applicable to slash commands. TYPE: bool DEFAULT: False

YIELDS	DESCRIPTION
CommandT[Self]	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)

RESTClient

RESTClient(
    app: RESTBotT,
    *,
    default_enabled_guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autosync: bool = True,
    autodefer: bool | AutodeferMode = True,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool = False,
    is_dm_enabled: bool = True,
    provided_locales: Sequence[Locale] | None = None,
    injector: Client | None = None
)

Bases: RESTClientBase[RESTBotAware]

The default REST client implementation. Effectively an alias for arc.RESTClientBase[hikari.RESTBotAware].

If you want to use GatewayBot, use GatewayClient instead.

PARAMETER	DESCRIPTION
app	The application this client is for. TYPE: GatewayBotAware
default_enabled_guilds	The guilds that commands will be registered in by default TYPE: Sequence[Snowflakeish | PartialGuild] | None DEFAULT: UNDEFINED
autosync	Whether to automatically sync commands on startup TYPE: bool DEFAULT: True
autodefer	Whether to automatically defer responses This applies to all commands, and can be overridden on a per-command basis. TYPE: bool | AutodeferMode DEFAULT: True
default_permissions	The default permissions for commands This applies to all commands, and can be overridden on a per-command basis. TYPE: Permissions | UndefinedType DEFAULT: UNDEFINED
is_nsfw	Whether commands are NSFW This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: False
is_dm_enabled	Whether commands are enabled in DMs This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: True
provided_locales	The locales that will be provided to the client by locale provider callbacks TYPE: Sequence[Locale] | None DEFAULT: None
injector	If you already have an injector instance, you may pass it here. Otherwise, a new one will be created by default. TYPE: Client | None DEFAULT: None

Example

import hikari
import arc

bot = hikari.RESTBot("TOKEN")
client = arc.RESTClient(bot)

Warning

The client will take over the hikari.CommandInteraction and hikari.AutocompleteInteraction listeners of the passed bot.

app property

app: AppT

The application this client is for.

application property

application: Application | None

The application object for this client. This is fetched on startup.

concurrency_limiter property

concurrency_limiter: ConcurrencyLimiterProto[Self] | None

The concurrency limiter for this client.

default_enabled_guilds property

default_enabled_guilds: Sequence[Snowflake] | UndefinedType

The guilds that slash commands will be registered in by default.

error_handler property

error_handler: ErrorHandlerCallbackT[Self] | None

The error handler for this client.

hooks property

hooks: MutableSequence[HookT[Self]]

The pre-execution hooks for this client.

injector property

injector: Client

The injector for this client.

is_rest property

is_rest: bool

Whether this client is a REST client.

is_started property

is_started: bool

Whether the client has started up.

owner_ids property

owner_ids: Sequence[Snowflake]

The IDs of the owners of this application.

plugins property

plugins: Mapping[str, PluginBase[Self]]

The plugins added to this client.

post_hooks property

post_hooks: MutableSequence[PostHookT[Self]]

The post-execution hooks for this client.

rest property

rest: RESTClient

The REST client of the underyling app.

add_hook

add_hook(
    hook: HookT[Self] | None = None,
) -> Self | Callable[[HookT[Self]], HookT[Self]]

Add a pre-execution hook to this client. This hook will be executed before every command that is added to this client.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: HookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_post_hook

add_injection_hook

add_injection_hook(
    hook: InjectionHookT[Self] | None = None,
) -> Self | Callable[[InjectionHookT[Self]], InjectionHookT[Self]]

Add an injection hook to this client. This hook will be called when a command is called, and an OverridingContext is passed, allowing you to inject dependencies for the command call.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: InjectionHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_injection_hook
async def inject(ctx: arc.GatewayContext, inj_ctx: arc.InjectorOverridingContext) -> None:
    foo: MyType = example_data[ctx.guild_id]
    inj_ctx.set_type_dependency(MyType, foo)

See Also

• Client.set_type_dependency

add_plugin

add_plugin(plugin: PluginBase[Self]) -> Self

Add a plugin to this client.

PARAMETER	DESCRIPTION
plugin	The plugin to add. TYPE: Plugin[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

add_post_hook

add_post_hook(
    hook: PostHookT[Self] | None = None,
) -> Self | Callable[[PostHookT[Self]], PostHookT[Self]]

Add a post-execution hook to this client. This hook will be executed after every command that is added to this client.

Warning

Post-execution hooks will be called even if the command callback raises an exception.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: PostHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_hook

add_shutdown_hook

add_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a shutdown hook for this client.

This will be called when the client shuts down.

PARAMETER	DESCRIPTION
hook	The shutdown hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.add_shutdown_hook(shutdown_hook)

add_startup_hook

add_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a startup hook for this client.

This will be called when the client starts up.

PARAMETER	DESCRIPTION
hook	The startup hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.add_startup_hook(startup_hook)

create_task

create_task(coro: Coroutine[Any, Any, T]) -> Task[T]

Create a task and add it to the client's internal task set.

This can be used for "fire and forget" task creation.

PARAMETER	DESCRIPTION
coro	The coroutine to create a task for. TYPE: Coroutine[Any, Any, T]

RETURNS	DESCRIPTION
Task[T]	The created task.

get_type_dependency

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

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 provided, this will raise an exception if the dependency does not exist. TYPE: DefaultT DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
T | DefaultT	The instance of the dependency, if it exists, otherwise default.

RAISES	DESCRIPTION
KeyError	If the dependency does not exist and default was not provided.

include

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

Decorator to add a command to this client.

Note

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

PARAMETER	DESCRIPTION
command	The command to add. TYPE: CommandBase[Self, BuilderT] DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If the command is already added to a plugin.

Example

@client.include # Add the command to the client.
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext) -> None:
    ...

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,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None,
    description_localizations: Mapping[Locale, str] | None = None,
    is_nsfw: bool = False
) -> SlashGroup[Self]

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: False

RETURNS	DESCRIPTION
SlashGroup[Self]	The slash command group that was created.
!!! note	Parameters left as hikari.UNDEFINED will be inherited from the parent 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]]

Decorator to inject dependencies into the decorated function.

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.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.inject_dependencies
def my_func(dep: MyDependency = arc.inject()) -> None:
    print(dep.value)

my_func() # Prints "Hello!"

See Also

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

load_extension

load_extension(path: str) -> Self

Load a python module with path path as an extension. This will import the module, and call it's loader function.

PARAMETER	DESCRIPTION
path	The path to the module to load. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the module does not have a loader.

Example

client = arc.GatewayClient(...)
client.load_extension("extension")

# In extension.py

plugin = arc.GatewayPlugin("test_plugin")

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

See Also

• @arc.loader
• Client.load_extensions_from
• Client.unload_extension

load_extensions_from

load_extensions_from(dir_path: str | Path, recursive: bool = False) -> Self

Load all python modules in a directory as extensions. This will import the modules, and call their loader functions.

PARAMETER	DESCRIPTION
dir_path	The path to the directory to load extensions from. TYPE: str
recursive	Whether to load extensions from subdirectories TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionLoadError	If dir_path does not exist or is not a directory.
ExtensionLoadError	If a module does not have a loader defined.

Example

client = arc.GatewayClient(...)
client.load_extensions_from("extensions/foo")

See Also

• @arc.loader
• Client.load_extension
• Client.unload_extension

on_autocomplete_interaction async

on_autocomplete_interaction(
    interaction: AutocompleteInteraction,
) -> InteractionAutocompleteBuilder | None

Should be called when an autocomplete interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: AutocompleteInteraction

RETURNS	DESCRIPTION
InteractionAutocompleteBuilder | None	The autocomplete builder to send back to Discord, if using a REST client.

on_command_interaction async

on_command_interaction(
    interaction: CommandInteraction,
) -> ResponseBuilderT | None

Should be called when a command interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: CommandInteraction

RETURNS	DESCRIPTION
ResponseBuilderT | None	The response builder to send back to Discord, if using a REST client.

on_restbot_shutdown async

on_restbot_shutdown(bot: RESTBotAware) -> None

A function that is called when the client is shut down.

PARAMETER	DESCRIPTION
bot	The bot that was shut down. TYPE: RESTBotAware

on_restbot_startup async

on_restbot_startup(bot: RESTBotAware) -> None

A function that is called when the client is started.

PARAMETER	DESCRIPTION
bot	The bot that was started. TYPE: RESTBotAware

purge_all_commands async

purge_all_commands(guild: SnowflakeishOr[PartialGuild] | None = None) -> None

Purge all commands registered on Discord. This can be used to clean up commands.

Warning

This will remove all commands registered on Discord, including commands not registered by this client.

PARAMETER	DESCRIPTION
guild	The guild to purge commands from If a guild is not provided, this will purge global commands. TYPE: SnowflakeishOr[PartialGuild] | None DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.purge_all_commands is called before Client.on_startup.

remove_injection_hook

remove_injection_hook(hook: InjectionHookT[Self]) -> Self

Remove an injection hook from this client.

PARAMETER	DESCRIPTION
hook	The hook to remove. TYPE: InjectionHookT[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the hook is not registered with this client.

remove_plugin

remove_plugin(plugin: str | PluginBase[Self]) -> Self

Remove a plugin from this client.

PARAMETER	DESCRIPTION
plugin	The plugin or name of the plugin to remove. TYPE: str | Plugin[Self]

RAISES	DESCRIPTION
ValueError	If there is no plugin with the given name.

RETURNS	DESCRIPTION
Self	The client for chaining calls.

resync_commands async

resync_commands() -> None

Synchronize the commands registered in this client with Discord.

Warning

Calling this is expensive, and should only be done when absolutely necessary. The client automatically syncs commands on startup, unless the autosync parameter is set to False when creating the client.

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.resync_commands is called before Client.on_startup.

set_command_locale_provider

set_command_locale_provider(
    provider: CommandLocaleRequestT | None = None,
) -> Self | Callable[[CommandLocaleRequestT], Self]

Decorator to set the command locale provider for this client.

This will be called for each command for each locale.

PARAMETER	DESCRIPTION
provider	The command locale provider to set. TYPE: CommandLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_command_locale_provider
def command_locale_provider(request: arc.CommandLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_command_locale_provider(command_locale_provider)

set_concurrency_limit

set_concurrency_limit(limiter: ConcurrencyLimiterProto[Self]) -> Self

Set the concurrency limiter for this client.

PARAMETER	DESCRIPTION
limiter	The concurrency limiter to set. TYPE: ConcurrencyLimiterProto[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

set_custom_locale_provider

set_custom_locale_provider(
    provider: CustomLocaleRequestT | None = None,
) -> Self | Callable[[CustomLocaleRequestT], Self]

Decorator to set the custom locale provider for this client.

This will be called for each custom locale request performed via Context.loc().

PARAMETER	DESCRIPTION
provider	The custom locale provider to set. TYPE: CustomLocaleRequestT DEFAULT: None

Example

@client.set_custom_locale_provider
def custom_locale_provider(request: arc.CustomLocaleRequest) -> str:
    ...

Or, as a function:

client.set_custom_locale_provider(custom_locale_provider)

set_error_handler

set_error_handler(
    handler: ErrorHandlerCallbackT[Self] | None = None,
) -> Self | Callable[[ErrorHandlerCallbackT[Self]], Self]

Decorator to set the error handler for this client.

This will be called when a command callback raises an exception that is not handled by any other error handlers.

PARAMETER	DESCRIPTION
handler	The error handler to set. TYPE: ErrorHandlerCallbackT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_error_handler
async def error_handler_func(ctx: arc.GatewayContext, exception: Exception) -> None:
    await ctx.respond(f"❌ Something went wrong: {exception}")

Warning

Errors that cannot be handled by the error handler should be re-raised. Otherwise tracebacks will not be printed to stderr.

Or, as a function:

client.set_error_handler(error_handler_func)

set_option_locale_provider

set_option_locale_provider(
    provider: OptionLocaleRequestT | None = None,
) -> Self | Callable[[OptionLocaleRequestT], Self]

Decorator to set the option locale provider for this client.

This will be called for each option of each command for each locale.

PARAMETER	DESCRIPTION
provider	The option locale provider to set. TYPE: OptionLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_option_locale_provider
def option_locale_provider(request: arc.OptionLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_option_locale_provider(option_locale_provider)

set_shutdown_hook

set_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the shutdown hook for this client.

This will be called when the client shuts down.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_shutdown_hook instead.

PARAMETER	DESCRIPTION
hook	The shutdown hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.set_shutdown_hook(shutdown_hook)

set_startup_hook

set_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the startup hook for this client.

This will be called when the client starts up.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_startup_hook instead.

PARAMETER	DESCRIPTION
hook	The startup hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.set_startup_hook(startup_hook)

set_type_dependency

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

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

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

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

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

client.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.include
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext, dep: MyDependency = arc.inject()) -> None:
    await ctx.respond(dep.value)

See Also

• Client.get_type_dependency A method to get dependencies for the client.

• Client.inject_dependencies A decorator to inject dependencies into arbitrary functions.

unload_extension

unload_extension(path: str) -> Self

Unload a python module with path path as an extension.

PARAMETER	DESCRIPTION
path	The path to the module to unload. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionUnloadError	If the module does not have an unloader or is not loaded.

See Also

• Client.load_extension
• Client.load_extensions_from

wait_until_started async

wait_until_started() -> None

Wait until the client has started up.

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. This is only applicable to slash commands. TYPE: bool DEFAULT: False

YIELDS	DESCRIPTION
CommandT[Self]	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)

RESTClientBase

RESTClientBase(
    app: RESTBotT,
    *,
    default_enabled_guilds: (
        Sequence[Snowflakeish | PartialGuild] | UndefinedType
    ) = hikari.UNDEFINED,
    autosync: bool = True,
    autodefer: bool | AutodeferMode = True,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool = False,
    is_dm_enabled: bool = True,
    provided_locales: Sequence[Locale] | None = None,
    injector: Client | None = None
)

Bases: Client[RESTBotT]

The base class for an arc client with REST support. This class primarily exists to allow for the creation of custom client types.

For the default implementation of a REST client, see RESTClient.

Warning

The client will take over the hikari.CommandInteraction and hikari.AutocompleteInteraction listeners of the passed bot.

PARAMETER	DESCRIPTION
app	The application this client is for. TYPE: GatewayBotAware
default_enabled_guilds	The guilds that commands will be registered in by default TYPE: Sequence[Snowflakeish | PartialGuild] | None DEFAULT: UNDEFINED
autosync	Whether to automatically sync commands on startup TYPE: bool DEFAULT: True
autodefer	Whether to automatically defer responses This applies to all commands, and can be overridden on a per-command basis. TYPE: bool | AutodeferMode DEFAULT: True
default_permissions	The default permissions for commands This applies to all commands, and can be overridden on a per-command basis. TYPE: Permissions | UndefinedType DEFAULT: UNDEFINED
is_nsfw	Whether commands are NSFW This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: False
is_dm_enabled	Whether commands are enabled in DMs This applies to all commands, and can be overridden on a per-command basis. TYPE: bool DEFAULT: True
provided_locales	The locales that will be provided to the client by locale provider callbacks TYPE: Sequence[Locale] | None DEFAULT: None
injector	If you already have an injector instance, you may pass it here. Otherwise, a new one will be created by default. TYPE: Client | None DEFAULT: None

app property

app: AppT

The application this client is for.

application property

application: Application | None

The application object for this client. This is fetched on startup.

concurrency_limiter property

concurrency_limiter: ConcurrencyLimiterProto[Self] | None

The concurrency limiter for this client.

default_enabled_guilds property

default_enabled_guilds: Sequence[Snowflake] | UndefinedType

The guilds that slash commands will be registered in by default.

error_handler property

error_handler: ErrorHandlerCallbackT[Self] | None

The error handler for this client.

hooks property

hooks: MutableSequence[HookT[Self]]

The pre-execution hooks for this client.

injector property

injector: Client

The injector for this client.

is_rest property

is_rest: bool

Whether this client is a REST client.

is_started property

is_started: bool

Whether the client has started up.

owner_ids property

owner_ids: Sequence[Snowflake]

The IDs of the owners of this application.

plugins property

plugins: Mapping[str, PluginBase[Self]]

The plugins added to this client.

post_hooks property

post_hooks: MutableSequence[PostHookT[Self]]

The post-execution hooks for this client.

rest property

rest: RESTClient

The REST client of the underyling app.

add_hook

add_hook(
    hook: HookT[Self] | None = None,
) -> Self | Callable[[HookT[Self]], HookT[Self]]

Add a pre-execution hook to this client. This hook will be executed before every command that is added to this client.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: HookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_post_hook

add_injection_hook

add_injection_hook(
    hook: InjectionHookT[Self] | None = None,
) -> Self | Callable[[InjectionHookT[Self]], InjectionHookT[Self]]

Add an injection hook to this client. This hook will be called when a command is called, and an OverridingContext is passed, allowing you to inject dependencies for the command call.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: InjectionHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_injection_hook
async def inject(ctx: arc.GatewayContext, inj_ctx: arc.InjectorOverridingContext) -> None:
    foo: MyType = example_data[ctx.guild_id]
    inj_ctx.set_type_dependency(MyType, foo)

See Also

• Client.set_type_dependency

add_plugin

add_plugin(plugin: PluginBase[Self]) -> Self

Add a plugin to this client.

PARAMETER	DESCRIPTION
plugin	The plugin to add. TYPE: Plugin[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

add_post_hook

add_post_hook(
    hook: PostHookT[Self] | None = None,
) -> Self | Callable[[PostHookT[Self]], PostHookT[Self]]

Add a post-execution hook to this client. This hook will be executed after every command that is added to this client.

Warning

Post-execution hooks will be called even if the command callback raises an exception.

PARAMETER	DESCRIPTION
hook	The hook to add. TYPE: PostHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

See Also

• Client.add_hook

add_shutdown_hook

add_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a shutdown hook for this client.

This will be called when the client shuts down.

PARAMETER	DESCRIPTION
hook	The shutdown hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.add_shutdown_hook(shutdown_hook)

add_startup_hook

add_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to add a startup hook for this client.

This will be called when the client starts up.

PARAMETER	DESCRIPTION
hook	The startup hook to add. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.add_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.add_startup_hook(startup_hook)

create_task

create_task(coro: Coroutine[Any, Any, T]) -> Task[T]

Create a task and add it to the client's internal task set.

This can be used for "fire and forget" task creation.

PARAMETER	DESCRIPTION
coro	The coroutine to create a task for. TYPE: Coroutine[Any, Any, T]

RETURNS	DESCRIPTION
Task[T]	The created task.

get_type_dependency

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

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 provided, this will raise an exception if the dependency does not exist. TYPE: DefaultT DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
T | DefaultT	The instance of the dependency, if it exists, otherwise default.

RAISES	DESCRIPTION
KeyError	If the dependency does not exist and default was not provided.

include

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

Decorator to add a command to this client.

Note

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

PARAMETER	DESCRIPTION
command	The command to add. TYPE: CommandBase[Self, BuilderT] DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If the command is already added to a plugin.

Example

@client.include # Add the command to the client.
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext) -> None:
    ...

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,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None,
    description_localizations: Mapping[Locale, str] | None = None,
    is_nsfw: bool = False
) -> SlashGroup[Self]

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: False

RETURNS	DESCRIPTION
SlashGroup[Self]	The slash command group that was created.
!!! note	Parameters left as hikari.UNDEFINED will be inherited from the parent 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]]

Decorator to inject dependencies into the decorated function.

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.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.inject_dependencies
def my_func(dep: MyDependency = arc.inject()) -> None:
    print(dep.value)

my_func() # Prints "Hello!"

See Also

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

load_extension

load_extension(path: str) -> Self

Load a python module with path path as an extension. This will import the module, and call it's loader function.

PARAMETER	DESCRIPTION
path	The path to the module to load. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the module does not have a loader.

Example

client = arc.GatewayClient(...)
client.load_extension("extension")

# In extension.py

plugin = arc.GatewayPlugin("test_plugin")

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

See Also

• @arc.loader
• Client.load_extensions_from
• Client.unload_extension

load_extensions_from

load_extensions_from(dir_path: str | Path, recursive: bool = False) -> Self

Load all python modules in a directory as extensions. This will import the modules, and call their loader functions.

PARAMETER	DESCRIPTION
dir_path	The path to the directory to load extensions from. TYPE: str
recursive	Whether to load extensions from subdirectories TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionLoadError	If dir_path does not exist or is not a directory.
ExtensionLoadError	If a module does not have a loader defined.

Example

client = arc.GatewayClient(...)
client.load_extensions_from("extensions/foo")

See Also

• @arc.loader
• Client.load_extension
• Client.unload_extension

on_autocomplete_interaction async

on_autocomplete_interaction(
    interaction: AutocompleteInteraction,
) -> InteractionAutocompleteBuilder | None

Should be called when an autocomplete interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: AutocompleteInteraction

RETURNS	DESCRIPTION
InteractionAutocompleteBuilder | None	The autocomplete builder to send back to Discord, if using a REST client.

on_command_interaction async

on_command_interaction(
    interaction: CommandInteraction,
) -> ResponseBuilderT | None

Should be called when a command interaction is sent by Discord.

PARAMETER	DESCRIPTION
interaction	The interaction that was created. TYPE: CommandInteraction

RETURNS	DESCRIPTION
ResponseBuilderT | None	The response builder to send back to Discord, if using a REST client.

on_restbot_shutdown async

on_restbot_shutdown(bot: RESTBotAware) -> None

A function that is called when the client is shut down.

PARAMETER	DESCRIPTION
bot	The bot that was shut down. TYPE: RESTBotAware

on_restbot_startup async

on_restbot_startup(bot: RESTBotAware) -> None

A function that is called when the client is started.

PARAMETER	DESCRIPTION
bot	The bot that was started. TYPE: RESTBotAware

purge_all_commands async

purge_all_commands(guild: SnowflakeishOr[PartialGuild] | None = None) -> None

Purge all commands registered on Discord. This can be used to clean up commands.

Warning

This will remove all commands registered on Discord, including commands not registered by this client.

PARAMETER	DESCRIPTION
guild	The guild to purge commands from If a guild is not provided, this will purge global commands. TYPE: SnowflakeishOr[PartialGuild] | None DEFAULT: None

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.purge_all_commands is called before Client.on_startup.

remove_injection_hook

remove_injection_hook(hook: InjectionHookT[Self]) -> Self

Remove an injection hook from this client.

PARAMETER	DESCRIPTION
hook	The hook to remove. TYPE: InjectionHookT[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ValueError	If the hook is not registered with this client.

remove_plugin

remove_plugin(plugin: str | PluginBase[Self]) -> Self

Remove a plugin from this client.

PARAMETER	DESCRIPTION
plugin	The plugin or name of the plugin to remove. TYPE: str | Plugin[Self]

RAISES	DESCRIPTION
ValueError	If there is no plugin with the given name.

RETURNS	DESCRIPTION
Self	The client for chaining calls.

resync_commands async

resync_commands() -> None

Synchronize the commands registered in this client with Discord.

Warning

Calling this is expensive, and should only be done when absolutely necessary. The client automatically syncs commands on startup, unless the autosync parameter is set to False when creating the client.

RAISES	DESCRIPTION
RuntimeError	If Client.application is None. This usually only happens if Client.resync_commands is called before Client.on_startup.

set_command_locale_provider

set_command_locale_provider(
    provider: CommandLocaleRequestT | None = None,
) -> Self | Callable[[CommandLocaleRequestT], Self]

Decorator to set the command locale provider for this client.

This will be called for each command for each locale.

PARAMETER	DESCRIPTION
provider	The command locale provider to set. TYPE: CommandLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_command_locale_provider
def command_locale_provider(request: arc.CommandLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_command_locale_provider(command_locale_provider)

set_concurrency_limit

set_concurrency_limit(limiter: ConcurrencyLimiterProto[Self]) -> Self

Set the concurrency limiter for this client.

PARAMETER	DESCRIPTION
limiter	The concurrency limiter to set. TYPE: ConcurrencyLimiterProto[Self]

RETURNS	DESCRIPTION
Self	The client for chaining calls.

set_custom_locale_provider

set_custom_locale_provider(
    provider: CustomLocaleRequestT | None = None,
) -> Self | Callable[[CustomLocaleRequestT], Self]

Decorator to set the custom locale provider for this client.

This will be called for each custom locale request performed via Context.loc().

PARAMETER	DESCRIPTION
provider	The custom locale provider to set. TYPE: CustomLocaleRequestT DEFAULT: None

Example

@client.set_custom_locale_provider
def custom_locale_provider(request: arc.CustomLocaleRequest) -> str:
    ...

Or, as a function:

client.set_custom_locale_provider(custom_locale_provider)

set_error_handler

set_error_handler(
    handler: ErrorHandlerCallbackT[Self] | None = None,
) -> Self | Callable[[ErrorHandlerCallbackT[Self]], Self]

Decorator to set the error handler for this client.

This will be called when a command callback raises an exception that is not handled by any other error handlers.

PARAMETER	DESCRIPTION
handler	The error handler to set. TYPE: ErrorHandlerCallbackT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_error_handler
async def error_handler_func(ctx: arc.GatewayContext, exception: Exception) -> None:
    await ctx.respond(f"❌ Something went wrong: {exception}")

Warning

Errors that cannot be handled by the error handler should be re-raised. Otherwise tracebacks will not be printed to stderr.

Or, as a function:

client.set_error_handler(error_handler_func)

set_option_locale_provider

set_option_locale_provider(
    provider: OptionLocaleRequestT | None = None,
) -> Self | Callable[[OptionLocaleRequestT], Self]

Decorator to set the option locale provider for this client.

This will be called for each option of each command for each locale.

PARAMETER	DESCRIPTION
provider	The option locale provider to set. TYPE: OptionLocaleRequestT DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_option_locale_provider
def option_locale_provider(request: arc.OptionLocaleRequest) -> arc.LocaleResponse:
    ...

Or, as a function:

client.set_option_locale_provider(option_locale_provider)

set_shutdown_hook

set_shutdown_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the shutdown hook for this client.

This will be called when the client shuts down.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_shutdown_hook instead.

PARAMETER	DESCRIPTION
hook	The shutdown hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_shutdown_hook
async def shutdown_hook(client: arc.GatewayClient) -> None:
    print("Client shut down!")

Or, as a function:

client.set_shutdown_hook(shutdown_hook)

set_startup_hook

set_startup_hook(
    hook: LifeCycleHookT[Self] | None = None,
) -> Self | Callable[[LifeCycleHookT[Self]], Self]

Decorator to set the startup hook for this client.

This will be called when the client starts up.

Deprecation Notice

This method is deprecated and will be removed in version 2.0.0. Use Client.add_startup_hook instead.

PARAMETER	DESCRIPTION
hook	The startup hook to set. TYPE: LifeCycleHookT[Self] DEFAULT: None

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

@client.set_startup_hook
async def startup_hook(client: arc.GatewayClient) -> None:
    print("Client started up!")

Or, as a function:

client.set_startup_hook(startup_hook)

set_type_dependency

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

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

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

RETURNS	DESCRIPTION
Self	The client for chaining calls.

Example

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

client.set_type_dependency(MyDependency, MyDependency("Hello!"))

@client.include
@arc.slash_command("cmd", "A command.")
async def cmd(ctx: arc.GatewayContext, dep: MyDependency = arc.inject()) -> None:
    await ctx.respond(dep.value)

See Also

• Client.get_type_dependency A method to get dependencies for the client.

• Client.inject_dependencies A decorator to inject dependencies into arbitrary functions.

unload_extension

unload_extension(path: str) -> Self

Unload a python module with path path as an extension.

PARAMETER	DESCRIPTION
path	The path to the module to unload. TYPE: str

RETURNS	DESCRIPTION
Self	The client for chaining calls.

RAISES	DESCRIPTION
ExtensionUnloadError	If the module does not have an unloader or is not loaded.

See Also

• Client.load_extension
• Client.load_extensions_from

wait_until_started async

wait_until_started() -> None

Wait until the client has started up.

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. This is only applicable to slash commands. TYPE: bool DEFAULT: False

YIELDS	DESCRIPTION
CommandT[Self]	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)