Command ABCs

CallableCommandBase

Bases: CommandBase[ClientT, BuilderT], CallableCommandProto[ClientT]

A top-level command that can be called directly. Note that this does not include subcommands, as those are options.

autodefer property

autodefer: AutodeferMode

The resolved autodefer configuration for this command.

callback instance-attribute

callback: CommandCallbackT[ClientT]

The callback to invoke when this command is called.

client property

client: ClientT

The client that is handling this command.

command_type abstractmethod property

command_type: CommandType

The type of command this object represents.

concurrency_limiter property writable

concurrency_limiter: ConcurrencyLimiterProto[ClientT] | None

The concurrency limiter for this command.

default_permissions property

default_permissions: Permissions | UndefinedType

The resolved default permissions for this command.

display_name property

display_name: str

The display name of this command. This is what is shown in the Discord client.

Note

Slash commands can also be mentioned, see SlashCommand.make_mention.

error_handler property writable

error_handler: ErrorHandlerCallbackT[ClientT] | None

The error handler for this command.

guilds class-attribute instance-attribute

guilds: Sequence[Snowflake] | UndefinedType = UNDEFINED

The guilds this command is available in.

hooks property

hooks: MutableSequence[HookT[ClientT]]

The pre-execution hooks for this command.

instances property

instances: Mapping[Snowflake | None, PartialCommand]

A mapping of guild IDs to command instances. None corresponds to the global instance, if any.

is_dm_enabled property

is_dm_enabled: bool

Whether this command is enabled in DMs.

is_nsfw property

is_nsfw: bool

Whether this command is NSFW. If true, the command will only be available in NSFW channels.

name instance-attribute

name: str

The name of this command.

name_localizations class-attribute instance-attribute

name_localizations: Mapping[Locale, str] = field(factory=dict)

The localizations for this command's name.

plugin property

plugin: PluginBase[ClientT] | None

The plugin that this command belongs to, if any.

post_hooks property

post_hooks: MutableSequence[PostHookT[ClientT]]

The post-execution hooks for this command.

qualified_name abstractmethod property

qualified_name: Sequence[str]

The fully qualified name of this command.

__call__ async

__call__(ctx: Context[ClientT], *args: Any, **kwargs: Any) -> None

Call the callback of the command with the given context and arguments.

PARAMETER	DESCRIPTION
ctx	The context to invoke this command with. TYPE: ContextT
args	The positional arguments to pass to the callback. TYPE: tuple[Any] DEFAULT: ()
kwargs	The keyword arguments to pass to the callback. TYPE: dict[str, Any] DEFAULT: {}

add_hook

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

Add a new pre-execution hook to this object.

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

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

RETURNS	DESCRIPTION
Self	This object for chaining.

add_post_hook

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

Add a new post-execution hook to this object.

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

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

RETURNS	DESCRIPTION
Self	This object for chaining.

invoke async

invoke(
    interaction: CommandInteraction, *args: Any, **kwargs: Any
) -> None | Future[ResponseBuilderT]

Invoke this command with the given interaction.

PARAMETER	DESCRIPTION
interaction	The interaction to invoke this command with. TYPE: CommandInteraction
args	The positional arguments to pass to the callback. TYPE: tuple[Any] DEFAULT: ()
kwargs	The keyword arguments to pass to the callback. TYPE: dict[str, Any] DEFAULT: {}

RETURNS	DESCRIPTION
None | Future[ResponseBuilderT]	If this is a REST client, returns the response builder.

RAISES	DESCRIPTION
RuntimeError	If this command has not been added to a client.

publish async

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

Publish this command to the given guild, or globally if no guild is provided.

PARAMETER	DESCRIPTION
guild	The guild to publish this command to. If None, publish globally. TYPE: Snowflakeish | None DEFAULT: None

RETURNS	DESCRIPTION
PartialCommand	The published command.

reset_all_limiters

reset_all_limiters(context: Context[ClientT]) -> None

Reset all limiter hooks for this command.

PARAMETER	DESCRIPTION
context	The context to reset the limiters for. TYPE: Context

set_concurrency_limiter

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

Set the concurrency limiter for this object.

set_error_handler

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

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

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

Example

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

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

    raise exc

Warning

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

unpublish async

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

Unpublish this command from the given guild, or globally if no guild is provided.

PARAMETER	DESCRIPTION
guild	The guild to unpublish this command from. If None, unpublish globally. TYPE: Snowflakeish | None DEFAULT: None

CallableCommandProto

Bases: CommandProto, Protocol[ClientT]

A protocol for any command-like object that can be called directly.

This includes commands and subcommands, but not groups or subgroups.

callback instance-attribute

callback: CommandCallbackT[ClientT]

The callback to invoke when this command is called.

command_type abstractmethod property

command_type: CommandType

The type of command this object represents.

display_name abstractmethod property

display_name: str

The display name of this command. This is what is shown in the Discord client.

Note

Slash commands can also be mentioned, see SlashCommand.make_mention.

hooks abstractmethod property

hooks: MutableSequence[HookT[ClientT]]

The pre-execution hooks for this command.

name instance-attribute

name: str

The name of the command.

name_localizations instance-attribute

name_localizations: Mapping[Locale, str]

The name of the command in different locales.

post_hooks abstractmethod property

post_hooks: MutableSequence[PostHookT[ClientT]]

The post-execution hooks for this command.

qualified_name abstractmethod property

qualified_name: Sequence[str]

The fully qualified name of this command.

__call__ abstractmethod async

__call__(ctx: Context[ClientT], *args: Any, **kwargs: Any) -> None

Call the callback of the command with the given context and arguments.

PARAMETER	DESCRIPTION
ctx	The context to invoke this command with. TYPE: ContextT
args	The positional arguments to pass to the callback. TYPE: tuple[Any] DEFAULT: ()
kwargs	The keyword arguments to pass to the callback. TYPE: dict[str, Any] DEFAULT: {}

invoke abstractmethod async

invoke(
    interaction: CommandInteraction, *args: Any, **kwargs: Any
) -> None | Future[ResponseBuilderT]

Invoke this command with the given context.

PARAMETER	DESCRIPTION
interaction	The interaction to invoke this command with. TYPE: CommandInteraction
args	The positional arguments to pass to the callback. TYPE: tuple[Any] DEFAULT: ()
kwargs	The keyword arguments to pass to the callback. TYPE: dict[str, Any] DEFAULT: {}

RETURNS	DESCRIPTION
None | Future[ResponseBuilderT]	If this is a REST client, returns the response builder.

RAISES	DESCRIPTION
RuntimeError	If this command has not been added to a client.

reset_all_limiters abstractmethod

reset_all_limiters(context: Context[ClientT]) -> None

Reset all limiter hooks for this command.

PARAMETER	DESCRIPTION
context	The context to reset the limiters for. TYPE: Context

CommandBase

Bases: HasErrorHandler[ClientT], Hookable[ClientT], HasConcurrencyLimiter[ClientT], Generic[ClientT, BuilderT]

An abstract base class for all application commands.

This notably does not include subcommands & subgroups as those are in reality options.

autodefer property

autodefer: AutodeferMode

The resolved autodefer configuration for this command.

client property

client: ClientT

The client that is handling this command.

command_type abstractmethod property

command_type: CommandType

The type of command this object represents.

concurrency_limiter property writable

concurrency_limiter: ConcurrencyLimiterProto[ClientT] | None

The concurrency limiter for this command.

default_permissions property

default_permissions: Permissions | UndefinedType

The resolved default permissions for this command.

display_name property

display_name: str

The display name of this command. This is what is shown in the Discord client.

Note

Slash commands can also be mentioned, see SlashCommand.make_mention.

error_handler property writable

error_handler: ErrorHandlerCallbackT[ClientT] | None

The error handler for this command.

guilds class-attribute instance-attribute

guilds: Sequence[Snowflake] | UndefinedType = UNDEFINED

The guilds this command is available in.

hooks property

hooks: MutableSequence[HookT[ClientT]]

The pre-execution hooks for this command.

instances property

instances: Mapping[Snowflake | None, PartialCommand]

A mapping of guild IDs to command instances. None corresponds to the global instance, if any.

is_dm_enabled property

is_dm_enabled: bool

Whether this command is enabled in DMs.

is_nsfw property

is_nsfw: bool

Whether this command is NSFW. If true, the command will only be available in NSFW channels.

name instance-attribute

name: str

The name of this command.

name_localizations class-attribute instance-attribute

name_localizations: Mapping[Locale, str] = field(factory=dict)

The localizations for this command's name.

plugin property

plugin: PluginBase[ClientT] | None

The plugin that this command belongs to, if any.

post_hooks property

post_hooks: MutableSequence[PostHookT[ClientT]]

The post-execution hooks for this command.

qualified_name abstractmethod property

qualified_name: Sequence[str]

The fully qualified name of this command.

add_hook

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

Add a new pre-execution hook to this object.

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

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

RETURNS	DESCRIPTION
Self	This object for chaining.

add_post_hook

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

Add a new post-execution hook to this object.

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

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

RETURNS	DESCRIPTION
Self	This object for chaining.

invoke abstractmethod async

invoke(
    interaction: CommandInteraction, *args: Any, **kwargs: Any
) -> None | Future[ResponseBuilderT]

Invoke this command with the given interaction.

PARAMETER	DESCRIPTION
interaction	The interaction to invoke this command with. TYPE: CommandInteraction
args	The positional arguments to pass to the callback. TYPE: tuple[Any] DEFAULT: ()
kwargs	The keyword arguments to pass to the callback. TYPE: dict[str, Any] DEFAULT: {}

RETURNS	DESCRIPTION
None | Future[ResponseBuilderT]	If this is a REST client, returns the response builder.

RAISES	DESCRIPTION
RuntimeError	If this command has not been added to a client.

publish async

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

Publish this command to the given guild, or globally if no guild is provided.

PARAMETER	DESCRIPTION
guild	The guild to publish this command to. If None, publish globally. TYPE: Snowflakeish | None DEFAULT: None

RETURNS	DESCRIPTION
PartialCommand	The published command.

set_concurrency_limiter

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

Set the concurrency limiter for this object.

set_error_handler

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

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

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

Example

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

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

    raise exc

Warning

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

unpublish async

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

Unpublish this command from the given guild, or globally if no guild is provided.

PARAMETER	DESCRIPTION
guild	The guild to unpublish this command from. If None, unpublish globally. TYPE: Snowflakeish | None DEFAULT: None

CommandProto

Bases: Protocol

A protocol for any command-like object. This includes commands, groups, subgroups, and subcommands.

command_type abstractmethod property

command_type: CommandType

The type of command this object represents.

display_name abstractmethod property

display_name: str

The display name of this command. This is what is shown in the Discord client.

Note

Slash commands can also be mentioned, see SlashCommand.make_mention.

name instance-attribute

name: str

The name of the command.

name_localizations instance-attribute

name_localizations: Mapping[Locale, str]

The name of the command in different locales.

qualified_name abstractmethod property

qualified_name: Sequence[str]

The fully qualified name of this command.

SubCommandBase

Bases: OptionBase[ClientT], HasErrorHandler[ClientT], Hookable[ClientT], HasConcurrencyLimiter[ClientT], Generic[ClientT, ParentT]

An abstract base class for all slash subcommands and subgroups.

concurrency_limiter property writable

concurrency_limiter: ConcurrencyLimiterProto[ClientT] | None

The concurrency limiter for this object.

description instance-attribute

description: str

The description of the option.

description_localizations class-attribute instance-attribute

description_localizations: Mapping[Locale, str] = field(factory=dict)

The description of the option in different locales.

display_name abstractmethod property

display_name: str

The display name of this command. This is what is shown in the Discord client.

Note

Slash commands can also be mentioned, see SlashCommand.make_mention.

error_handler property writable

error_handler: ErrorHandlerCallbackT[ClientT] | None

The error handler for this object.

hooks property

hooks: MutableSequence[HookT[ClientT]]

The pre-execution hooks for this object.

name instance-attribute

name: str

The name of the option.

name_localizations class-attribute instance-attribute

name_localizations: Mapping[Locale, str] = field(factory=dict)

The name of the option in different locales.

option_type abstractmethod property

option_type: OptionType

The type of the option. Used to register the command.

parent property

parent: ParentT

The parent of this subcommand or subgroup.

post_hooks property

post_hooks: MutableSequence[PostHookT[ClientT]]

The post-execution hooks for this object.

add_hook

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

Add a new pre-execution hook to this object.

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

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

RETURNS	DESCRIPTION
Self	This object for chaining.

add_post_hook

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

Add a new post-execution hook to this object.

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

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

RETURNS	DESCRIPTION
Self	This object for chaining.

reset_all_limiters

reset_all_limiters(context: Context[ClientT]) -> None

Reset all limiter hooks for this command.

PARAMETER	DESCRIPTION
context	The context to reset the limiters for. TYPE: Context

set_concurrency_limiter

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

Set the concurrency limiter for this object.

set_error_handler

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

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

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

Example

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

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

    raise exc

Warning

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

to_command_option

to_command_option() -> CommandOption

Convert this option to a hikari.CommandOption.