Skip to content

User Command#

UserCommand #

Bases: CallableCommandBase[ClientT, ContextMenuCommandBuilder]

A context menu command that is invoked by right-clicking a user.

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 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 #

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 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
) -> Future[ResponseBuilderT] | None

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

user_command #

user_command(
    name: str,
    *,
    guilds: (
        Sequence[PartialGuild | Snowflakeish] | UndefinedType
    ) = hikari.UNDEFINED,
    is_dm_enabled: bool | UndefinedType = hikari.UNDEFINED,
    is_nsfw: bool | UndefinedType = hikari.UNDEFINED,
    autodefer: bool | AutodeferMode | UndefinedType = hikari.UNDEFINED,
    default_permissions: Permissions | UndefinedType = hikari.UNDEFINED,
    name_localizations: Mapping[Locale, str] | None = None
) -> Callable[[UserCommandCallbackT[ClientT]], UserCommand[ClientT]]

A decorator that creates a context-menu command on a user.

Note

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

PARAMETER DESCRIPTION
name

The name of the command.

TYPE: str

guilds

The guilds this command should be enabled in, if left as undefined, the command is global

TYPE: Sequence[PartialGuild | Snowflakeish] | UndefinedType DEFAULT: UNDEFINED

is_dm_enabled

Whether this command is enabled in DMs.

TYPE: bool | UndefinedType DEFAULT: UNDEFINED

is_nsfw

Whether this command is NSFW.

TYPE: bool | UndefinedType DEFAULT: UNDEFINED

autodefer

If True, this command will be automatically deferred if it takes longer than 2 seconds to respond

TYPE: bool | AutodeferMode | UndefinedType DEFAULT: UNDEFINED

default_permissions

The default permissions for this command. Keep in mind that guild administrators can change this, it should only be used to provide safe defaults.

TYPE: Permissions | UndefinedType DEFAULT: UNDEFINED

name_localizations

The localizations for this command's name.

TYPE: Mapping[Locale, str] | None DEFAULT: None

Example
@client.include
@arc.user_command(name="Say Hi", description="Say hi!")
async def hi_user(ctx: arc.GatewayContext, user: hikari.User) -> None:
    await ctx.respond(f"Hey {user.mention}!")