Skip to content

tanjun.components#

Standard implementation of Tanjun's "components" used to manage separate features within a client.

OnCallbackSig = typing.Union[collections.Callable[Ellipsis, collections.Coroutine[typing.Any, typing.Any, None]], collections.Callable[Ellipsis, None]] module-attribute #

Type hint of a on_open or on_close component callback.

These support dependency injection, should expect no positional arguments and should return None.

AbstractComponentLoader #

Bases: abc.ABC

Abstract interface used for loading utility into a standard tanjun.Component.

load_into_component(component) abstractmethod #

Load the object into the component.

PARAMETER DESCRIPTION
component

The component this object should be loaded into.

TYPE: tanjun.Component

Component #

Bases: tanjun.Component

Standard implementation of tanjun.abc.Component.

This is a collcetion of commands (both message and slash), hooks and listener callbacks which can be added to a generic client.

Note

This implementation supports dependency injection for its checks, command callbacks and listeners when linked to a client which supports dependency injection.

__init__(*, name=None, strict=False) #

Initialise a new component.

PARAMETER DESCRIPTION
name

The component's identifier.

If not provided then this will be a random string.

TYPE: typing.Optional[str] DEFAULT: None

strict

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.

TYPE: bool DEFAULT: False

add_check(check) #

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

PARAMETER DESCRIPTION
check

The check to add.

TYPE: tanjun.CheckSig

RETURNS DESCRIPTION
Self

This component to enable method chaining.

add_client_callback(name, callback) #

Add a client callback.

PARAMETER DESCRIPTION
name

The name this callback is being registered to.

This is case-insensitive.

TYPE: typing.Union[str, tanjun.ClientCallbackNames]

callback

The callback to register.

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.

TYPE: tanjun.MetaEventSig

RETURNS DESCRIPTION
Self

The client instance to enable chained calls.

add_command(command) #

Add a command to this component.

PARAMETER DESCRIPTION
command

The command to add.

TYPE: tanjun.ExecutableCommand[typing.Any]

RETURNS DESCRIPTION
Self

The current component to allow for chaining.

add_message_command(command) #

Add a message command to the component.

PARAMETER DESCRIPTION
command

The command to add.

TYPE: tanjun.MessageCommand[typing.Any]

RETURNS DESCRIPTION
Self

The component to allow method chaining.

RAISES DESCRIPTION
ValueError

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

add_on_close(callback) #

Add a close callback to this component.

Note

Unlike the closing and closed client callbacks, this is only called for the current component's lifetime and is guaranteed to be called regardless of when the component was added to a client.

PARAMETER DESCRIPTION
callback

The close callback to add to this component.

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

TYPE: OnCallbackSig

RETURNS DESCRIPTION
Self

The component object to enable call chaining.

add_on_open(callback) #

Add a open callback to this component.

Note

Unlike the starting and started client callbacks, this is only called for the current component's lifetime and is guaranteed to be called regardless of when the component was added to a client.

PARAMETER DESCRIPTION
callback

The open callback to add to this component.

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

TYPE: OnCallbackSig

RETURNS DESCRIPTION
Self

The component object to enable call chaining.

add_schedule(schedule) #

Add a schedule to the component.

PARAMETER DESCRIPTION
schedule

The schedule to add.

TYPE: schedules_.AbstractSchedule

RETURNS DESCRIPTION
Self

The component itself for chaining.

checks() property #

Collection of the checks being run against every command execution in this component.

get_client_callbacks(name) #

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

PARAMETER DESCRIPTION
name

The name to get the callbacks registered for.

This is case-insensitive.

TYPE: typing.Union[str, tanjun.ClientCallbackNames]

RETURNS DESCRIPTION
collections.abc.Collection[MetaEventSig]

Collection of the callbacks for the provided name.

hooks() property #

The general command hooks set for this component, if any.

load_from_scope(*, include_globals=False, scope=None) #

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

Note

This will load schedules which support and commands AbstractComponentLoader (all standard implementations support this) and will ignore commands which are owned by command groups.

Note

This will detect entries from the calling scope which implement tanjun.components.AbstractComponentLoader unless scope is passed but this isn't possible in a stack-less python implementation; in stack-less environments the scope will have to be explicitly passed as scope.

PARAMETER DESCRIPTION
include_globals

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.

TYPE: bool DEFAULT: False

scope

The scope to detect entries which implement tanjun.components.AbstractComponentLoader from.

This overrides the default usage of stackframe introspection.

TYPE: typing.Optional[collections.Mapping[str, typing.Any]] DEFAULT: None

RETURNS DESCRIPTION
Self

The current component to allow for chaining.

RAISES DESCRIPTION
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_loader(*, copy=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 [tanjun.Client.load_modules][], [tanjun.Client.unload_modules][] and [tanjun.Client.reload_modules][].

PARAMETER DESCRIPTION
copy

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

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
tanjun.abc.ClientLoader

The loader for this component.

menu_hooks() property #

The menu command hooks set for this component, if any.

message_hooks() property #

The message command hooks set for this component, if any.

remove_check(check) #

Remove a command check from this component.

PARAMETER DESCRIPTION
check

The check to remove.

TYPE: tanjun.CheckSig

RETURNS DESCRIPTION
Self

This component to enable method chaining.

RAISES DESCRIPTION
ValueError

If the check is not registered with this component.

remove_client_callback(name, callback) #

Remove a client callback.

PARAMETER DESCRIPTION
name

The name this callback is being registered to.

This is case-insensitive.

TYPE: str

callback

The callback to remove from the client's callbacks.

TYPE: tanjun.MetaEventSig

RAISES DESCRIPTION
KeyError

If the provided name isn't found.

ValueError

If the provided callback isn't found.

RETURNS DESCRIPTION
Self

The client instance to enable chained calls.

remove_command(command) #

Remove a command from this component.

PARAMETER DESCRIPTION
command

The command to remove.

TYPE: tanjun.ExecutableCommand[typing.Any]

RETURNS DESCRIPTION
Self

This component to enable method chaining.

remove_schedule(schedule) #

Remove a schedule from the component.

PARAMETER DESCRIPTION
schedule

The schedule to remove

TYPE: schedules_.AbstractSchedule

RETURNS DESCRIPTION
Self

The component itself for chaining.

RAISES DESCRIPTION
ValueError

If the schedule isn't registered.

schedules() property #

Collection of the schedules registered to this component.

set_default_app_command_permissions(permissions) #

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

Warning

This may be overridden by guild staff and does not apply to admins.

PARAMETER DESCRIPTION
permissions

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 tanjun.abc.AppCommand.default_member_permissions and if this is left as None then this config will be inherited from the parent client.

TYPE: typing.Union[int, hikari.Permissions, None]

RETURNS DESCRIPTION
Self

This client to enable method chaining.

set_dms_enabled_for_app_cmds(state) #

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

PARAMETER DESCRIPTION
state

Whether to enable this component's commands in DMs.

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

TYPE: typing.Optional[bool]

RETURNS DESCRIPTION
Self

This client to enable method chaining.

set_ephemeral_default(state) #

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

PARAMETER DESCRIPTION
state

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.

TYPE: typing.Optional[bool]

RETURNS DESCRIPTION
Self

This component to enable method chaining.

set_hooks(hooks) #

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

PARAMETER DESCRIPTION
hooks

The command hooks to set.

TYPE: typing.Optional[tanjun.AnyHooks]

RETURNS DESCRIPTION
Self

This component to enable method chaining.

set_menu_hooks(hooks) #

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

PARAMETER DESCRIPTION
hooks

The menu command hooks to set.

TYPE: typing.Optional[tanjun.MenuHooks]

RETURNS DESCRIPTION
Self

This component to enable method chaining.

set_message_hooks(hooks) #

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

PARAMETER DESCRIPTION
hooks

The message command hooks to set.

TYPE: typing.Optional[tanjun.MessageHooks]

RETURNS DESCRIPTION
Self

This component to enable method chaining.

set_slash_hooks(hooks) #

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

PARAMETER DESCRIPTION
hooks

The slash command hooks to set.

TYPE: typing.Optional[tanjun.SlashHooks]

RETURNS DESCRIPTION
Self

This component to enable method chaining.

slash_hooks() property #

The slash command hooks set for this component, if any.

with_check(check) #

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

PARAMETER DESCRIPTION
check

The check to add.

TYPE: tanjun.abc.CheckSig

RETURNS DESCRIPTION
tanjun.abc.CheckSig

The added check.

with_client_callback(name) #

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
PARAMETER DESCRIPTION
name

The name this callback is being registered to.

This is case-insensitive.

TYPE: typing.Union[str, tanjun.ClientCallbackNames]

RETURNS DESCRIPTION
collections.abc.Callable[[tanjun.abc.MetaEventSig], tanjun.abc.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.

with_command(command=None, /, *, copy=False, follow_wrapped=False) #

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}")
PARAMETER DESCRIPTION
command

The command to add to this component.

TYPE: typing.Optional[_CommandT] DEFAULT: None

copy

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

TYPE: bool DEFAULT: False

follow_wrapped

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

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.abc.ExecutableCommand

The added command.

with_on_close(callback) #

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

Note

Unlike the closing and closed client callbacks, this is only called for the current component's lifetime and is guaranteed to be called regardless of when the component was added to a client.

PARAMETER DESCRIPTION
callback

The close callback to add to this component.

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

TYPE: OnCallbackSig

RETURNS DESCRIPTION
OnCallbackSig

The added close callback.

with_on_open(callback) #

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

Note

Unlike the starting and started client callbacks, this is only called for the current component's lifetime and is guaranteed to be called regardless of when the component was added to a client.

PARAMETER DESCRIPTION
callback

The open callback to add to this component.

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

TYPE: OnCallbackSig

RETURNS DESCRIPTION
OnCallbackSig

The added open callback.

with_schedule(schedule) #

Add a schedule to the component through a decorator call.

Example#

This may be used in conjunction with tanjun.as_interval.

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

The schedule to add.

TYPE: tanjun.schedules.AbstractSchedule

RETURNS DESCRIPTION
tanjun.schedules.AbstractSchedule

The added schedule.