Skip to content

tanjun.components#

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

OnCallbackSig module-attribute #

OnCallbackSig = Callable[..., Coroutine[Any, Any, None] | None]

Type hint of a on_open or on_close component callback.

This represents the signatures def (...) -> None and async def (...) -> None where dependency injection is supported.

AbstractComponentLoader #

Bases: ABC

Abstract interface used for loading utility into a standard Component.

load_into_component abstractmethod #

load_into_component(component)

Load the object into the component.

Parameters:

  • component (Component) –

    The component this object should be loaded into.

Component #

Bases: 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.

checks property #

checks

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

hooks property #

hooks

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

menu_hooks property #

menu_hooks

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

message_hooks property #

message_hooks

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

schedules property #

schedules

Collection of the schedules registered to this component.

slash_hooks property #

slash_hooks

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

__init__ #

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

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

add_check(*checks)

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

add_client_callback(name, /, *callbacks)

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

add_command(command)

Add a command to this component.

Parameters:

Returns:

  • Self –

    The current component to allow for chaining.

add_message_command #

add_message_command(command)

Add a message command to the component.

Parameters:

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

add_on_close(*callbacks)

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.

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

add_on_open(*callbacks)

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.

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

add_schedule(schedule)

Add a schedule to the component.

Parameters:

Returns:

  • Self –

    The component itself for chaining.

get_client_callbacks #

get_client_callbacks(name)

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

load_from_scope(*, scope: collections.Mapping[str, typing.Any] | None = None) -> Self

load_from_scope(*, include_globals: bool = False) -> Self

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

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

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

remove_check(check)

Remove a command check from this component.

Parameters:

Returns:

  • Self –

    This component to enable method chaining.

Raises:

  • ValueError –

    If the check is not registered with this component.

remove_client_callback #

remove_client_callback(name, callback)

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

remove_command(command)

Remove a command from this component.

Parameters:

Returns:

  • Self –

    This component to enable method chaining.

remove_schedule #

remove_schedule(schedule)

Remove a schedule from the component.

Parameters:

Returns:

  • Self –

    The component itself for chaining.

Raises:

  • ValueError –

    If the schedule isn't registered.

set_case_sensitive #

set_case_sensitive(state)

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

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.

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

set_dms_enabled_for_app_cmds(state)

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

set_ephemeral_default(state)

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 #

set_hooks(hooks)

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

set_menu_hooks(hooks)

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

set_message_hooks(hooks)

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

set_slash_hooks(hooks)

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.

with_check #

with_check(check)

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

Parameters:

  • check (CheckSig) –

    The check to add.

Returns:

  • CheckSig –

    The added check.

with_client_callback #

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

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.

with_command #

with_command(command: _CommandT) -> _CommandT

with_command(*, copy: bool = False, follow_wrapped: bool = False) -> collections.Callable[[_CommandT], _CommandT]

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}")

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.

with_on_close #

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.

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:

with_on_open #

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.

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:

with_schedule #

with_schedule(schedule)

Add a schedule to the component through a decorator call.

Example

This may be used in conjunction with tanjun.as_interval or tanjun.as_time_schedule.

@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.