tanjun#

Initialise a Tanjun client.

Parameters:

• rest (RESTClient) –

  The Hikari REST client this will use.

• cache (Cache | None, default: None ) –

  The Hikari cache client this will use if applicable.

• events (EventManager | None, default: None ) –

  The Hikari event manager client this will use if applicable.

  This is necessary for message command dispatch and will also be necessary for interaction command dispatch if server isn't provided.

• server (InteractionServer | None, default: None ) –

  The Hikari interaction server client this will use if applicable.

  This is used for interaction command dispatch if interaction events aren't being received from the event manager.

• shards (ShardAware | None, default: None ) –

  The Hikari shard aware client this will use if applicable.

• voice (VoiceComponent | None, default: None ) –

  The Hikari voice component this will use if applicable.

• event_managed (bool, default: False ) –

  Whether or not this client is managed by the event manager.

  An event managed client will be automatically started and closed based on Hikari's lifetime events.

  This can only be passed as True if events is also provided.

• injector (Client | None, default: None ) –

  The alluka client this should use for dependency injection.

  If not provided then either the "local" Alluka client will be used or the client will initialise its own DI client.

• mention_prefix (bool, default: False ) –

  Whether or not mention prefixes should be automatically set when this client is first started.

  It should be noted that this only applies to message commands.

• declare_global_commands (SnowflakeishSequence[PartialGuild] | SnowflakeishOr[PartialGuild] | bool, default: False ) –

  Whether or not to automatically set global slash commands when this client is first started.

  If one or more guild objects/IDs are passed here then the registered global commands will be set on the specified guild(s) at startup rather than globally.

  The endpoint this uses has a strict ratelimit which, as of writing, only allows for 2 requests per minute (with that ratelimit either being per-guild if targeting a specific guild otherwise globally).

• command_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of top level command names to IDs of the existing commands to update.

  This will be used for all application commands but in cases where commands have overlapping names, message_ids and user_ids will take priority over this for their relevant command type.

  This field is complementary to declare_global_commands and, while it isn't necessarily required, this will in some situations help avoid permissions which were previously set for a command from being lost after a rename.

  This currently isn't supported when multiple guild IDs are passed for declare_global_commands.

• message_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of message context menu command names to the IDs of existing commands to update.

• user_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of user context menu command names to the IDs of existing commands to update.

Raises:

• ValueError –

  Raises for the following reasons:

  • If event_managed is True when event_manager is None.
  • If command_ids is passed when multiple guild ids are provided for declare_global_commands.
  • If command_ids is passed when declare_global_commands is False.

Add a generic check to this client.

This will be applied to both message and slash command execution.

Parameters:

• *checks (AnyCheckSig, default: () ) –

  The checks to add. These may be either synchronous or asynchronous and must take one positional argument of type tanjun.abc.Context with dependency injection being supported for its keyword arguments.

Returns:

• Self –

  The client instance to enable chained calls.

Add a component to this client.

Parameters:

• component (Component) –

  The component to move to this client.

Returns:

• Self –

  The client instance to allow chained calls.

Raises:

• ValueError –

  If the component's name is already registered.

Add a prefix used to filter message command calls.

This will be matched against the first character(s) in a message's content to determine whether the message command search stage of execution should be initiated.

Parameters:

• prefixes (Iterable[str] | str) –

  Either a single string or an iterable of strings to be used as prefixes.

Returns:

• Self –

  The client instance to enable chained calls.

Close the client.

Raises:

• RuntimeError –

  If the client isn't running.

Fetch the ID of the application this client is linked to.

Returns:

• Snowflake –

  The application ID of the application this client is linked to.

Build a Client from a gateway bot.

Parameters:

• bot (ShardAware & RESTAware & EventManagerAware) –

  The bot client to build from.

  This will be used to infer the relevant Hikari clients to use.

• event_managed (bool, default: True ) –

  Whether or not this client is managed by the event manager.

  An event managed client will be automatically started and closed based on Hikari's lifetime events.

• injector (Client | None, default: None ) –

  The alluka client this should use for dependency injection.

  If not provided then the client will initialise its own DI client.

• mention_prefix (bool, default: False ) –

  Whether or not mention prefixes should be automatically set when this client is first started.

  It should be noted that this only applies to message commands.

• declare_global_commands (SnowflakeishSequence[PartialGuild] | SnowflakeishOr[PartialGuild] | bool, default: False ) –

  Whether or not to automatically set global slash commands when this client is first started.

  If one or more guild objects/IDs are passed here then the registered global commands will be set on the specified guild(s) at startup rather than globally.

  The endpoint this uses has a strict ratelimit which, as of writing, only allows for 2 requests per minute (with that ratelimit either being per-guild if targeting a specific guild otherwise globally).

• command_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of top level command names to IDs of the commands to update.

  This field is complementary to declare_global_commands and, while it isn't necessarily required, this will in some situations help avoid permissions which were previously set for a command from being lost after a rename.

  This currently isn't supported when multiple guild IDs are passed for declare_global_commands.

• message_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of message context menu command names to the IDs of existing commands to update.

• user_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of user context menu command names to the IDs of existing commands to update.

Build a Client from a hikari.RESTBotAware instance.

Parameters:

• bot (RESTBotAware) –

  The bot client to build from.

• declare_global_commands (SnowflakeishSequence[PartialGuild] | SnowflakeishOr[PartialGuild] | bool, default: False ) –

  Whether or not to automatically set global slash commands when this client is first started.

  If one or more guild objects/IDs are passed here then the registered global commands will be set on the specified guild(s) at startup rather than globally.

  The endpoint this uses has a strict ratelimit which, as of writing, only allows for 2 requests per minute (with that ratelimit either being per-guild if targeting a specific guild otherwise globally).

• bot_managed (bool, default: False ) –

  Whether the client should be managed by the REST bot.

  A REST bot managed client will be automatically started and closed based on the REST bot's startup and shutdown callbacks.

• injector (Client | None, default: None ) –

  The alluka client this should use for dependency injection.

  If not provided then the client will initialise its own DI client.

• command_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of top level command names to IDs of the existing commands to update.

  This will be used for all application commands but in cases where commands have overlapping names, message_ids and user_ids will take priority over this for their relevant command type.

  This field is complementary to declare_global_commands and, while it isn't necessarily required, this will in some situations help avoid permissions which were previously set for a command from being lost after a rename.

  This currently isn't supported when multiple guild IDs are passed for declare_global_commands.

• message_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of message context menu command names to the IDs of existing commands to update.

• user_ids (Mapping[str, SnowflakeishOr[PartialCommand]] | None, default: None ) –

  If provided, a mapping of user context menu command names to the IDs of existing commands to update.

Execute a command autocomplete based on received REST requests.

Parameters:

• interaction (AutocompleteInteraction) –

  The interaction to execute autocomplete based on.

Returns:

• InteractionAutocompleteBuilder –

  The initial response to send back to Discord.

Execute an app command based on received REST requests.

Parameters:

• interaction (CommandInteraction) –

  The interaction to execute a command based on.

Returns:

• InteractionMessageBuilder | InteractionDeferredBuilder | InteractionModalBuilder –

  The initial response to send back to Discord.

Execute command autocomplete based on a received gateway interaction create.

Parameters:

• interaction (AutocompleteInteraction) –

  The interaction to execute a command based on.

Execute an app command based on a received gateway interaction create.

Parameters:

• interaction (CommandInteraction) –

  The interaction to execute a command based on.

Handle a gateway interaction create event.

This will execute both application command and autocomplete interactions.

Parameters:

• event (InteractionCreateEvent) –

  The event to execute commands based on.

Execute a message command based on a gateway event.

Parameters:

• event (MessageCreateEvent) –

  The event to handle.

Start the client.

If mention_prefix was passed to Client.__init__ or Client.from_gateway_bot then this function may make a fetch request to Discord if it cannot get the current user from the cache.

Raises:

• RuntimeError –

  If the client is already active.

Remove a check from the client.

Parameters:

• check (AnyCheckSig) –

  The check to remove.

Raises:

• ValueError –

  If the check was not previously added.

Remove a message content prefix from the client.

Parameters:

• prefix (str) –

  The prefix to remove.

Raises:

• ValueError –

  If the prefix is not registered with the client.

Returns:

• Self –

  The client instance to enable chained calls.

Set when this client should automatically defer execution of commands.

Parameters:

• time (float | None) –

  The time in seconds to defer interaction command responses after.

Set the autocomplete context maker to use when creating contexts.

Parameters:

• maker (_AutocompleteContextMakerProto, default: AutocompleteContext ) –

  The autocomplete context maker to use.

  This is a callback which should match the signature of tanjun.AutocompleteContext.__init__ and return an instance of tanjun.AutocompleteContext.

Returns:

• Self –

  This client to enable method chaining.

Set whether this client defaults to being case sensitive for message commands.

Parameters:

• state (bool) –

  Whether this client's message commands should be matched case-sensitively.

  This may be overridden by component specific configuration.

Set the default member permissions needed for this client's commands.

Parameters:

• permissions (int | Permissions) –

  The default member permissions needed for this client's application commands.

  This may be overridden by AppCommand.default_member_permissions and Component.default_app_cmd_permissions; if this is left as None then this config will be inherited from the parent client.

Returns:

• Self –

  This client to enable method chaining.

Set whether this clients's commands should be enabled in DMs.

Parameters:

• state (bool) –

  Whether to enable this client's commands in DMs.

  This may be overridden by AppCommand.is_dm_enabled and Component.dms_enabled_for_app_cmds; if this is left as None then this config will be inherited from the parent client.

Returns:

• Self –

  This client to enable method chaining.

Set whether slash contexts spawned by this client should default to ephemeral responses.

This defaults to False if not explicitly set.

Parameters:

• state (bool) –

  Whether slash command contexts executed in this client should should default to ephemeral.

  This will be overridden by any response calls which specify flags.

Returns:

• Self –

  This client to enable method chaining.

Alias of Client.declare_global_commands.

Set type based dependency injection based on the hikari traits found in bot.

This is a short hand for calling Client.set_type_dependency for all the hikari trait types bot is valid for with bot.

Parameters:

• bot (RESTAware) –

  The hikari client to set dependency injectors for.

Set the general command execution hooks for this client.

The callbacks within this hook will be added to every slash and message command execution started by this client.

Parameters:

• hooks (AnyHooks | None) –

  The general command execution hooks to set for this client.

  Passing None will remove all hooks.

Returns:

• Self –

  The client instance to enable chained calls.

Set whether or not message commands execution should be limited to "human" users.

Parameters:

• value (bool, default: True ) –

  Whether or not message commands execution should be limited to "human" users.

  Passing True here will prevent message commands from being executed based on webhook and bot messages.

Set the kind of interactions this client should execute.

Parameters:

• accepts (InteractionAcceptsEnum) –

  Bitfield of the interaction types this client should execute.

Raises:

• RuntimeError –

  If called while the client is running.

Set the response message for when an interaction command is not found.

Parameters:

• message (str | None) –

  The message to respond with when an interaction command isn't found.

Set the autocomplete context maker to use when creating contexts.

Parameters:

• maker (_MenuContextMakerProto, default: MenuContext ) –

  The autocomplete context maker to use.

  This is a callback which should match the signature of tanjun.MenuContext.__init__ and return an instance of tanjun.MenuContext.

Returns:

• Self –

  This client to enable method chaining.

Set the menu command execution hooks for this client.

The callbacks within this hook will be added to every menu command execution started by this client.

Parameters:

• hooks (MenuHooks | None) –

  The menu context specific command execution hooks to set for this client.

  Passing None will remove the hooks.

Returns:

• Self –

  The client instance to enable chained calls.

Set the response message for when a menu command is not found.

Parameters:

• message (str | None) –

  The message to respond with when a menu command isn't found.

Set the kind of messages commands should be executed based on.

Parameters:

• accepts (MessageAcceptsEnum) –

  The type of messages commands should be executed based on.

Raises:

• RuntimeError –

  If called while the client is running.

• ValueError –

  If accepts is set to anything other than MessageAcceptsEnum.NONE when the client doesn't have a linked event manager.

Set the message context maker to use when creating context for a message.

Parameters:

• maker (_MessageContextMakerProto, default: MessageContext ) –

  The message context maker to use.

  This is a callback which should match the signature of tanjun.MessageContext.__init__ and return an instance of tanjun.MessageContext.

Returns:

• Self –

  This client to enable method chaining.

Set the message command execution hooks for this client.

The callbacks within this hook will be added to every message command execution started by this client.

Parameters:

• hooks (MessageHooks | None) –

  The message context specific command execution hooks to set for this client.

  Passing None will remove all hooks.

Returns:

• Self –

  The client instance to enable chained calls.

Set the callback used to retrieve message prefixes set for the relevant guild.

Parameters:

• getter (PrefixGetterSig | None) –

  The callback which'll be used to retrieve prefixes for the guild a message context is from. If None is passed here then the callback will be unset.

  This should be an async callback which one argument of type tanjun.abc.MessageContext and returns an iterable of string prefixes. Dependency injection is supported for this callback's keyword arguments.

Returns:

• Self –

  The client instance to enable chained calls.

Set the slash context maker to use when creating context for a slash command.

Parameters:

• maker (_SlashContextMakerProto, default: SlashContext ) –

  The slash context maker to use.

  This is a callback which should match the signature of tanjun.SlashContext.__init__ and return an instance of tanjun.SlashContext.

Returns:

• Self –

  This client to enable method chaining.

Set the slash command execution hooks for this client.

The callbacks within this hook will be added to every slash command execution started by this client.

Parameters:

• hooks (SlashHooks | None) –

  The slash context specific command execution hooks to set for this client.

  Passing None will remove the hooks.

Returns:

• Self –

  The client instance to enable chained calls.

Set the response message for when a slash command is not found.

Parameters:

• message (str | None) –

  The message to respond with when a slash command isn't found.

Add a check to this client through a decorator call.

Parameters:

• check (CheckSig) –

  The check to add. This may be either synchronous or asynchronous and must take one positional argument of type tanjun.abc.Context with dependency injection being supported for its keyword arguments.

Returns:

• CheckSig –

  The added check.

Set the prefix getter callback for this client through decorator call.

Examples:

client = tanjun.Client.from_rest_bot(bot)

@client.with_prefix_getter
async def prefix_getter(ctx: tanjun.abc.MessageContext) -> collections.abc.Iterable[str]:
    raise NotImplementedError

Parameters:

• getter (PrefixGetterSig) –

  The callback which'll be to retrieve prefixes for the guild a message event is from.

  This should be an async callback which one argument of type tanjun.abc.MessageContext and returns an iterable of string prefixes. Dependency injection is supported for this callback's keyword arguments.

Returns:

• PrefixGetterSig –

  The registered callback.

Initialise a command error.

Parameters:

• content (UndefinedOr[Any], default: UNDEFINED ) –

  If provided, the message content to respond with.

  If this is a hikari.Embed and no embed nor embeds kwarg is provided, then this will instead be treated as an embed. This allows for simpler syntax when sending an embed alone.

  Likewise, if this is a hikari.Resource, then the content is instead treated as an attachment if no attachment and no attachments kwargs are provided.

• delete_after (timedelta | float | int | None, default: None ) –

  If provided, the seconds after which the response message should be deleted.

  Slash command responses can only be deleted within 15 minutes of the command being received.

• attachment (UndefinedOr[Resourceish], default: UNDEFINED ) –

  A singular attachment to respond with.

• attachments (UndefinedOr[Sequence[Resourceish]], default: UNDEFINED ) –

  A sequence of attachments to respond with.

• component (UndefinedOr[ComponentBuilder], default: UNDEFINED ) –

  If provided, builder object of the component to include in this response.

• components (UndefinedOr[Sequence[ComponentBuilder]], default: UNDEFINED ) –

  If provided, a sequence of the component builder objects to include in this response.

• embed (UndefinedOr[Embed], default: UNDEFINED ) –

  An embed to respond with.

• embeds (UndefinedOr[Sequence[Embed]], default: UNDEFINED ) –

  A sequence of embeds to respond with.

• mentions_everyone (UndefinedOr[bool], default: UNDEFINED ) –

  If provided, whether the message should parse @everyone/@here mentions.

• user_mentions (SnowflakeishSequence[PartialUser] | bool | UndefinedType, default: UNDEFINED ) –

  If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed.

  Alternatively this may be a collection of hikari.Snowflake, or hikari.PartialUser derivatives to enforce mentioning specific users.

• role_mentions (SnowflakeishSequence[PartialRole] | bool | UndefinedType, default: UNDEFINED ) –

  If provided, and True, all mentions will be parsed. If provided, and False, no mentions will be parsed.

  Alternatively this may be a collection of hikari.Snowflake, or hikari.PartialRole derivatives to enforce mentioning specific roles.

Raises:

• ValueError –

  Raised for any of the following reasons:

  • When both attachment and attachments are provided.
  • When both component and components are passed.
  • When both embed and embeds are passed.
  • If more than 100 entries are passed for role_mentions.
  • If more than 100 entries are passed for user_mentions.

Send this error as a command response.

Parameters:

• ctx (Context) –

  The command call context to respond to.

• ensure_result (bool, default: False ) –

  Ensure that this call will always return a message object.

  If True then this will always return hikari.Message, otherwise this will return hikari.Message | None.

  It's worth noting that, under certain scenarios within the slash command flow, this may lead to an extre request being made.

Raises:

• ValueError –

  If delete_after would be more than 15 minutes after the slash command was called.

• BadRequestError –

  This may be raised in several discrete situations, such as messages being empty with no attachments or embeds; messages with more than 2000 characters in them, embeds that exceed one of the many embed limits; too many attachments; attachments that are too large; invalid image URLs in embeds; too many components.

• UnauthorizedError –

  If you are unauthorized to make the request (invalid/missing token).

• ForbiddenError –

  If you are missing the SEND_MESSAGES in the channel or the person you are trying to message has the DM's disabled.

• NotFoundError –

  If the channel is not found.

• RateLimitTooLongError –

  Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

• InternalServerError –

  If an internal error occurs on Discord while handling the request.

Initialise a new component.

Parameters:

• name (str | None, default: None ) –

  The component's identifier.

  If not provided then this will be a random string.

• strict (bool, default: False ) –

  Whether this component should use a stricter (more optimal) approach for message command search.

  When this is True, message command names will not be allowed to contain spaces and will have to be unique to one command within the component.

Add a command check to this component to be used for all its commands.

Parameters:

• *checks (AnyCheckSig, default: () ) –

  The checks to add.

Returns:

• Self –

  This component to enable method chaining.

Add a client callback.

Parameters:

• name (str | ClientCallbackNames) –

  The name this callback is being registered to.

  This is case-insensitive.

• *callbacks (MetaEventSig, default: () ) –

  The callbacks to register.

  These may be sync or async and must return None. The positional and keyword arguments a callback should expect depend on implementation detail around the name being subscribed to.

Returns:

• Self –

  The client instance to enable chained calls.

Add a command to this component.

Parameters:

• command (ExecutableCommand[Any]) –

  The command to add.

Returns:

• Self –

  The current component to allow for chaining.

Add a message command to the component.

Parameters:

• command (MessageCommand[Any]) –

  The command to add.

Returns:

• Self –

  The component to allow method chaining.

Raises:

• ValueError –

  If one of the command's name is already registered in a strict component.

Add a close callback to this component.

Parameters:

• *callbacks (OnCallbackSig, default: () ) –

  The close callbacks to add to this component.

  This should take no positional arguments, return None and may take use injected dependencies.

Returns:

• Self –

  The component object to enable call chaining.

Add a open callback to this component.

Parameters:

• *callbacks (OnCallbackSig, default: () ) –

  The open callbacks to add to this component.

  These should take no positional arguments, return None and may request injected dependencies.

Returns:

• Self –

  The component object to enable call chaining.

Add a schedule to the component.

Parameters:

• schedule (AbstractSchedule) –

  The schedule to add.

Returns:

• Self –

  The component itself for chaining.

Get a collection of the callbacks registered for a specific name.

Parameters:

• name (str | ClientCallbackNames) –

  The name to get the callbacks registered for.

  This is case-insensitive.

Returns:

• Collection[MetaEventSig] –

  Collection of the callbacks for the provided name.

Load entries such as top-level commands into the component from the calling scope.

Parameters:

• include_globals (bool, default: False ) –

  Whether to include global variables (along with local) while detecting from the calling scope.

  This cannot be True when scope is provided and will only ever be needed when the local scope is different from the global scope.

• scope (Mapping[str, Any] | None, default: None ) –

  The scope to detect entries which implement AbstractComponentLoader from.

  This overrides the default usage of stackframe introspection.

Returns:

• Self –

  The current component to allow for chaining.

Raises:

• RuntimeError –

  If this is called in a python implementation which doesn't support stack frame inspection when scope is not provided.

• ValueError –

  If scope is provided when include_globals is True.

Make a loader/unloader for this component.

This enables loading, unloading and reloading of this component into a client by targeting the module using Client.load_modules, Client.unload_modules and Client.reload_modules.

Parameters:

• copy (bool, default: True ) –

  Whether to copy the component before loading it into a client.

Returns:

• ClientLoader –

  The loader for this component.

Remove a command check from this component.

Parameters:

• check (AnyCheckSig) –

  The check to remove.

Returns:

• Self –

  This component to enable method chaining.

Raises:

• ValueError –

  If the check is not registered with this component.

Remove a client callback.

Parameters:

• name (str) –

  The name this callback is being registered to.

  This is case-insensitive.

• callback (MetaEventSig) –

  The callback to remove from the client's callbacks.

Raises:

• KeyError –

  If the provided name isn't found.

• ValueError –

  If the provided callback isn't found.

Returns:

• Self –

  The client instance to enable chained calls.

Remove a command from this component.

Parameters:

• command (ExecutableCommand[Any]) –

  The command to remove.

Returns:

• Self –

  This component to enable method chaining.

Remove a schedule from the component.

Parameters:

• schedule (AbstractSchedule) –

  The schedule to remove

Returns:

• Self –

  The component itself for chaining.

Raises:

• ValueError –

  If the schedule isn't registered.

Set whether this component defaults to being case sensitive for component.

Parameters:

• state (bool | None) –

  Whether this component's message commands should be matched case-sensitively.

  If this is left as None then the client's case-sensitive setting will be used.

Set the default member permissions needed for this component's commands.

Parameters:

• permissions (int | Permissions | None) –

  The default member permissions needed for this component's application commands.

  If this is left as None then this config will be inherited from the parent client.

  This may be overridden by AppCommand.default_member_permissions and if this is left as None then this config will be inherited from the parent client.

Returns:

• Self –

  This client to enable method chaining.

Set whether this component's commands should be enabled in DMs.

Parameters:

• state (bool | None) –

  Whether to enable this component's commands in DMs.

  This may be overridden by AppCommand.is_dm_enabled and if this is left as None then this config will be inherited from the parent client.

Returns:

• Self –

  This client to enable method chaining.

Set whether slash contexts executed in this component should default to ephemeral responses.

Parameters:

• state (bool | None) –

  Whether slash command contexts executed in this component should should default to ephemeral. This will be overridden by any response calls which specify flags.

  Setting this to None will let the default set on the parent client propagate and decide the ephemeral default behaviour.

Returns:

• Self –

  This component to enable method chaining.

Set hooks to be called during the execution of all of this component's commands.

Parameters:

• hooks (AnyHooks | None) –

  The command hooks to set.

Returns:

• Self –

  This component to enable method chaining.

Set hooks to be called during the execution of this component's menu commands.

Parameters:

• hooks (MenuHooks | None) –

  The menu command hooks to set.

Returns:

• Self –

  This component to enable method chaining.

Set hooks to be called during the execution of this component's message commands.

Parameters:

• hooks (MessageHooks | None) –

  The message command hooks to set.

Returns:

• Self –

  This component to enable method chaining.

Set hooks to be called during the execution of this component's slash commands.

Parameters:

• hooks (SlashHooks | None) –

  The slash command hooks to set.

Returns:

• Self –

  This component to enable method chaining.

Add a general command check to this component through a decorator call.

Parameters:

• check (CheckSig) –

  The check to add.

Returns:

• CheckSig –

  The added check.

Add a client callback through a decorator call.

Examples:

client = tanjun.Client.from_rest_bot(bot)

@client.with_client_callback("closed")
async def on_close() -> None:
    raise NotImplementedError

Parameters:

• name (str | ClientCallbackNames) –

  The name this callback is being registered to.

  This is case-insensitive.

Returns:

• Callable[[MetaEventSig], MetaEventSig] –

  Decorator callback used to register the client callback.

  This may be sync or async and must return None. The positional and keyword arguments a callback should expect depend on implementation detail around the name being subscribed to.

Add a command to this component through a decorator call.

Examples:

This may be used inconjunction with tanjun.as_slash_command and tanjun.as_message_command.

@component.with_command
@tanjun.with_slash_str_option("option_name", "option description")
@tanjun.as_slash_command("command_name", "command description")
async def slash_command(ctx: tanjun.abc.Context, arg: str) -> None:
    await ctx.respond(f"Hi {arg}")

@component.with_command
@tanjun.with_argument("argument_name")
@tanjun.as_message_command("command_name")
async def message_command(ctx: tanjun.abc.Context, arg: str) -> None:
    await ctx.respond(f"Hi {arg}")

Parameters:

• command (_CommandT | None, default: None ) –

  The command to add to this component.

• copy (bool, default: False ) –

  Whether to copy the command before adding it to this component.

• follow_wrapped (bool, default: False ) –

  Whether to also add any commands command wraps in a decorator call chain.

Returns:

• ExecutableCommand –

  The added command.

Add a close callback to this component through a decorator call.

Parameters:

• callback (OnCallbackSig) –

  The close callback to add to this component.

  This should take no positional arguments, return None and may request injected dependencies.

Returns:

• OnCallbackSig –

  The added close callback.

Add a open callback to this component through a decorator call.

Parameters:

• callback (OnCallbackSig) –

  The open callback to add to this component.

  This should take no positional arguments, return None and may take use injected dependencies.

Returns:

• OnCallbackSig –

  The added open callback.

Add a schedule to the component through a decorator call.

@component.with_schedule
@tanjun.as_interval(60)
async def my_schedule():
    print("I'm running every minute!")

Parameters:

• schedule (AbstractSchedule) –

  The schedule to add.

Returns:

• AbstractSchedule –

  The added schedule.

Initialise a conversion error.

Parameters:

• parameter (str) –

  The parameter this was raised by.

• errors (Iterable[ValueError], default: () ) –

  An iterable of the source value errors which were raised during conversion.

Initialise a command hook object.

Add this hook object to a command.

Examples:

This method may be used as a command decorator:

@standard_hooks.add_to_command
@as_message_command("command")
async def command_command(ctx: tanjun.abc.Context) -> None:
    await ctx.respond("You've called a command!")

Parameters:

• command (ExecutableCommand) –

  The command to add the hooks to.

Returns:

• ExecutableCommand –

  The command with the hooks added.

Copy this hook object.

Set the error callback for this hook object.

Parameters:

• callback (ErrorHookSig[_ContextT_contra] | None) –

  The callback to set for this hook. This will remove any previously set callbacks.

  This callback should take two positional arguments (of type tanjun.abc.Context and Exception) and may be either synchronous or asynchronous.

  Returning True indicates that the error should be suppressed, False that it should be re-raised and None that no decision has been made. This will be accounted for along with the decisions other error hooks make by majority rule.

Returns:

• Self –

  The hook object to enable method chaining.

Set the parser error callback for this hook object.

Parameters:

• callback (ParserHookSig[_ContextT_contra] | None) –

  The callback to set for this hook. This will remove any previously set callbacks.

  This callback should take two positional arguments (of type tanjun.abc.Context and tanjun.ParserError), return None and may be either synchronous or asynchronous.

  It's worth noting that, unlike general error handlers, this will always suppress the error.

Returns:

• Self –

  The hook object to enable method chaining.

Set the success callback for this hook object.

Parameters:

• callback (HookSig[_ContextT_contra] | None) –

  The callback to set for this hook. This will remove any previously set callbacks.

  This callback should take one positional argument (of type tanjun.abc.Context), return None and may be either synchronous or asynchronous.

Returns:

• Self –

  The hook object to enable method chaining.

Set the post-execution callback for this hook object.

Parameters:

• callback (HookSig[_ContextT_contra] | None) –

  The callback to set for this hook. This will remove any previously set callbacks.

  This callback should take one positional argument (of type tanjun.abc.Context), return None and may be either synchronous or asynchronous.

Returns:

• Self –

  The hook object to enable method chaining.

Set the pre-execution callback for this hook object.

Parameters:

• callback (HookSig[_ContextT_contra] | None) –

  The callback to set for this hook. This will remove any previously set callbacks.

  This callback should take one positional argument (of type tanjun.abc.Context), return None and may be either synchronous or asynchronous.

Returns:

• Self –

  The hook object to enable method chaining.

Initialise a hot reloader.

Parameters:

• commands_guild (SnowflakeishOr[PartialGuild] | None, default: None ) –

  Object or ID of the guild to declare commands in if redeclare_cmds_after is not None.

• interval (int | float | timedelta, default: timedelta(microseconds=500000) ) –

  How often this should scan files and directories for changes in seconds.

• redeclare_cmds_after (int | float | timedelta | None, default: timedelta(seconds=10) ) –

  How often to redeclare application commands after a change to the commands is detected.

  If None is passed here then this will not redeclare the application's commands.

• unload_on_delete (bool, default: True ) –

  Whether this should unload modules when their relevant file is deleted.

Add a directory for this hot reloader to track.

Parameters:

• directory (str | Path) –

  Path of the directory to hot reload.

• namespace (str | None, default: None ) –

  The python namespace this directory's modules should be imported from, if applicable.

  This work as {namespace}.{file.name.removesuffix(".py")} and will have the same behaviour as when a str is passed to Client.load_modules if passed.

  If left as None then this will have the same behaviour as when a pathlib.Path is passed to Client.load_modules.

Returns:

• Self –

  The hot reloader to enable chained calls.

Raises:

• FileNotFoundError –

  If the directory cannot be found

Asynchronous variant of HotReloader.add_directory.

Unlike HotReloader.add_directory, this method will run blocking code in a background thread.

For more information on the behaviour of this method see the documentation for HotReloader.add_directory.

Add modules for this hot reloader to track.

Parameters:

• *paths (str | Path, default: () ) –

  Module paths for this hot reloader to track.

  This has the same behaviour as [tanjun.abc.Client.load_modules][ for how [pathlib.Path][] and str are treated.

Raises:

• FileNotFoundError –

  If the module's file doesn't exist anymore.

• ModuleNotFoundError –

  If the str module path cannot be imported.

Asynchronous variant of HotReloader.add_modules.

Unlike HotReloader.add_modules, this method will run blocking code in a background thread.

For more information on the behaviour of this method see the documentation for HotReloader.add_modules.

Add this to a tanjun.abc.Client instance.

This registers start and closing callbacks which handle the lifetime of this and adds this as a type dependency.

Parameters:

• client (Client) –

  The client to link this hot reloader to.

Manually scan this hot reloader's tracked modules for changes.

Parameters:

• client (Client) –

  The client to reload and unload modules in.

Start the hot reloader.

Raises:

• RuntimeError –

  If the hot reloader is already running.

Stop the hot reloader.

Raises:

• RuntimeError –

  If the hot reloader isn't running.

Acquire an concurrency lock on a bucket through an async context manager.

Parameters:

• bucket_id (str) –

  The concurrency bucket to acquire.

• ctx (Context) –

  The context to acquire this resource lock with.

• error (Callable[[], Exception], default: lambda: CommandError('This resource is currently busy; please try again later.') ) –

  Callback which returns the error that's raised when the lock couldn't be acquired due to being at it's limit.

  This will be raised on entering the returned context manager and defaults to an English command error.

Returns:

• AbstractAsyncContextManager[None] –

  The context manager which'll acquire and release this concurrency lock.

Raises:

• CommandError –

  The default error that's raised while entering the returned async context manager if it couldn't acquire the lock.

Add this concurrency manager to a tanjun client.

Parameters:

• client (Client) –

  The client to add this concurrency manager to.

Stop the concurrency manager.

Raises:

• RuntimeError –

  If the concurrency manager is not running.

Disable a concurrency limit bucket.

This will stop the bucket from ever hitting a concurrency limit and also prevents the bucket from defaulting.

Parameters:

• bucket_id (str) –

  The bucket to disable.

Returns:

• Self –

  This concurrency manager to allow for chaining.

Start the concurrency manager.

Raises:

• RuntimeError –

  If the concurrency manager is already running. If called in a thread with no running event loop.

Set the concurrency limit for a specific bucket.

Parameters:

• bucket_id (str) –

  The ID of the bucket to set the concurrency limit for.

• resource (BucketResource) –

  The type of resource to target for the concurrency limit.

• limit (int) –

  The maximum number of concurrent uses to allow.

Returns:

• Self –

  The concurrency manager to allow call chaining.

Raises:

• ValueError –

  If any of the following cases are met:

  • If an invalid resource is passed.
  • If limit is less 0 or negative.

Set a custom concurrency limit resource.

Parameters:

• resource (AbstractConcurrencyBucket) –

  Object which handles the concurrency limits for these buckets.

• bucket_ids (str, default: () ) –

  IDs of buckets to set this custom resource for.

Returns:

• Self –

  The concurrency manager to allow call chaining.

Examples:

class CustomBucket(tanjun.dependencies.AbstractConcurrencyBucket):
    __slots__ = ()

    async def try_acquire(
        self, bucket_id: str, ctx: tanjun.abc.Context, /
    ) -> bool:
        # ResourceDepleted should be raised if this couldn't be acquired.
        raise tanjun.dependencies.ResourceDepleted

    async def release(
        self, bucket_id: str, ctx: tanjun.abc.Context, /
    ) -> None:
        ...

(
    tanjun.dependencies.InMemoryConcurrencyLimiter()
    .set_custom_bucket(CustomBucket(), "BUCKET_ID", "OTHER_BUCKET_ID")
)

Acquire a cooldown lock on a bucket through an async context manager.

Parameters:

• bucket_id (str) –

  The cooldown bucket to acquire.

• ctx (Context) –

  The context to acquire this resource lock with.

• error (Callable[[datetime | None], Exception], default: lambda cooldown: CommandError('This command is currently in cooldown.' + f' Try again {from_datetime(cooldown, style='R')}.' if cooldown else '') ) –

  Callback which returns the error that's raised when the lock couldn't be acquired due to it being on cooldown.

  This will be raised on entering the returned context manager and defaults to an English command error.

Returns:

• AbstractAsyncContextManager[None] –

  The context manager which'll acquire and release this cooldown lock.

Raises:

• CommandError –

  The default error that's raised while entering the returned async context manager if it couldn't acquire the lock.

Add this cooldown manager to a tanjun client.

Parameters:

• client (Client) –

  The client to add this cooldown manager to.

Stop the cooldown manager.

Raises:

• RuntimeError –

  If the cooldown manager is not running.

Disable a cooldown bucket.

This will stop the bucket from ever hitting a cooldown and also prevents the bucket from defaulting.

Parameters:

• bucket_id (str) –

  The bucket to disable.

Returns:

• Self –

  This cooldown manager to allow for chaining.

Deprecated function for incrementing a cooldown.

Use AbstractCooldownManager.acquire and AbstractCooldownManager.release.

Start the cooldown manager.

Raises:

• RuntimeError –

  If the cooldown manager is already running. If called in a thread with no running event loop.

Set the cooldown for a specific bucket.

Parameters:

• bucket_id (str) –

  The ID of the bucket to set the cooldown for.

• resource (BucketResource) –

  The type of resource to target for the cooldown.

• limit (int) –

  The number of uses per cooldown period.

• reset_after (int | float | timedelta) –

  The cooldown period.

Returns:

• Self –

  The cooldown manager to allow call chaining.

Raises:

• ValueError –

  If any of the following cases are met:

  • If an invalid resource is passed.
  • If reset_after or limit are negative, 0 or invalid.
  • If limit is less 0 or negative.

Set a custom cooldown limit resource.

Parameters:

• resource (AbstractCooldownBucket) –

  Object which handles the cooldowns for these buckets.

• bucket_ids (str, default: () ) –

  IDs of buckets to set this custom resource for.

Returns:

• Self –

  The cooldown manager to allow call chaining.

Examples:

class CustomBucket(tanjun.dependencies.AbstractCooldownBucket):
    __slots__ = ()

    async def try_acquire(
        self, bucket_id: str, ctx: tanjun.abc.Context, /
    ) -> None:
        # CooldownDepleted should be raised if this couldn't be acquired.
        raise tanjun.dependencies.CooldownDepleted(None)

    async def release(
        self, bucket_id: str, ctx: tanjun.abc.Context, /
    ) -> None:
        ...

(
    tanjun.dependencies.InMemoryCooldownManager()
    .set_custom_bucket(CustomBucket(), "BUCKET_ID", "OTHER_BUCKET_ID")
)