Client ABC#

Client #

Client(
    app: AppT,
    *,
    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: Generic[AppT], ABC

The abstract base class for an arc client. See GatewayClientBase and RESTClientBase for implementations.

PARAMETER	DESCRIPTION
`app`	The application this client is for. TYPE: `AppT`
`default_enabled_guilds`	The guilds that slash commands will be registered in by default TYPE: `Sequence[Snowflake] \| None` DEFAULT: `UNDEFINED`
`autosync`	Whether to automatically sync commands on startup TYPE: `bool` DEFAULT: `True`
`autodefer`	Whether to automatically defer commands that take longer than 2 seconds to respond 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 to mark commands as NSFW This applies to all commands, and can be overridden on a per-command basis. TYPE: `bool` DEFAULT: `False`
`is_dm_enabled`	Whether to enable commands 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 `abstractmethod` `property` #

is_rest: bool

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

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

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.

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)

Client ABC#

Client #

app property #

application property #

concurrency_limiter property #

default_enabled_guilds property #

error_handler property #

hooks property #

injector property #

is_rest abstractmethod property #

is_started property #

owner_ids property #

plugins property #

post_hooks property #

rest property #

add_hook #

add_injection_hook #

add_plugin #

add_post_hook #

add_shutdown_hook #

add_startup_hook #

create_task #

get_type_dependency #

include #

include_slash_group #

inject_dependencies #

load_extension #

load_extensions_from #

on_autocomplete_interaction async #

on_command_interaction async #

purge_all_commands async #

remove_injection_hook #

remove_plugin #

resync_commands async #

set_command_locale_provider #

set_concurrency_limit #

set_custom_locale_provider #

set_error_handler #

set_option_locale_provider #

set_shutdown_hook #

set_startup_hook #

set_type_dependency #

unload_extension #

wait_until_started async #

walk_commands #

app `property` #

application `property` #

concurrency_limiter `property` #

default_enabled_guilds `property` #

error_handler `property` #

hooks `property` #

injector `property` #

is_rest `abstractmethod` `property` #

is_started `property` #

owner_ids `property` #

plugins `property` #

post_hooks `property` #

rest `property` #

on_autocomplete_interaction `async` #

on_command_interaction `async` #

purge_all_commands `async` #

resync_commands `async` #

wait_until_started `async` #