API reference 

Raises

DuplicateCommand – If the command shares a name or alias with an existing command.
TypeError – If aliases is not a list or a tuple.

remove_command(name: str) → MessageCommand

Removes a MessageCommand from the Bot, and its yami.Module if it has one.

Parameters: name (str) – The name of the command to remove.
Returns: The command that was removed.
Return type: MessageCommand
Raises: CommandNotFound – When the command was not found.

iter_commands() → Generator[MessageCommand, None, None]

Iterates the bots commands.

Returns: A generator over the commands.
Return type: Generator
Yields: MessageCommand – Each command.

iter_modules() → Generator[Module, None, None]

Iterates over the modules attached to the bot. This will included both loaded and unloaded modules.

Returns: A generator over the modules.
Return type: Generator
Yields: Module – Each module.

iter_loaded_modules() → Generator[Module, None, None]

Iterates over the modules attached to the bot. This will only include loaded modules.

Returns: A generator over the modules.
Return type: Generator
Yields: Module – Each loaded module.

get_command(name: str) → yami.commands.MessageCommand | None

Gets a command.

Parameters: name (str) – The name or alias of the command to get.
Returns: The command, or None if not found.
Return type: MessageCommand | None

get_module(name: str) → yami.modules.Module | None

Gets a module.

Parameters: name (str) – The name of the module to get.
Returns: The module, or None if not found.
Return type: yami.Module | None

command(name: Optional[str] = None, description: str = '', *, aliases: Sequence[str] = (), raise_conversion: bool = False, invoke_with: bool = False) → Callable[[...], Any]

Decorator to add a MessageCommand to the bot. This should be placed immediately above the command callback. Any checks should be placed above this decorator.

Parameters

name (str) – The name of the command. Defaults to the function name.
description (str) – The command description. If omitted, the callbacks docstring will be used instead.

Keyword Arguments

aliases (Sequence [str]) – A list or tuple of aliases for the command.
raise_conversion (bool) – Whether or not to raise an exception when a type hint conversion for the command arguments fails.

Returns

A message command crafted from the callback, and decorator arguments.

Return type

checks

Module containing all the Yami Checks.

class yami.checks.Check

Bases: ABC

Base class all Yami checks inherit from.

classmethod get_name() → str

Returns the name of this Check subclass.

Returns: The name of the class.
Return type: str

abstract async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.is_owner

Bases: Check

Fails if the author of the command is not the bots owner.

Hint

Who is the bots owner?

Any user with an id matching one of the ids passed into the bots constructor for the kwarg owner_ids.
The application owner fetched from Discord if no owner_ids were passed to the constructor.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.is_in_guild

Bases: Check

Fails if the command was not run in a guild.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.is_in_dm

Bases: Check

Fails if the command was not run in a DM.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.has_roles(*roles: str | int)

Bases: Check

Fails if the author does not have all of the roles passed to this check decorator.

This is inherently an is_in_guild check as well, because a user cannot have a role outside of a guild.

Parameters: *roles (str | int) – The name or id of the role or roles the user must have.
Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.has_any_role(*roles: str | int)

Bases: Check

Fails if the author does not have any of the role names or ids passed to this check.

This is inherently an is_in_guild check as well, because a user cannot have a role outside of a guild.

Parameters: *roles (str | int) – The names or ids of the roles the user must have at least one of.
Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.has_perms(**perms: bool)

Bases: Check

Fails if the author does not have all of the specified permissions. This accumulates all permissions the user has.

This is inherently an is_in_guild check as well, because a user cannot have a role outside of a guild.

Warning

If you pass something like manage_messages=False to this check, it will do nothing.

It will not require the user to have the permission. Make sure you use manage_messages=True.

Keyword Arguments: **perms (bool) – Keyword arguments for each of the available hikari perms.
Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.custom_check(check: Union[Callable[[MessageContext], Any], Check], *, message: str = '')

Bases: Check

A custom check.

Hint

If the check returns False or raises an Exception the check will fail.
If the check returns True or any other value without raising an error, it will pass.

Parameters

check (Callable [[MessageContext], Any]) –

The callback function that should be used for the check.

Note

It should accept one argument of type MessageContext and return False or raise an error if it fails.
This can be an async, or sync function.

Keyword Arguments

message – (str): The optional message to use in the CheckFailed exception. The default message is "a custom check was failed".

Raises

CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.checks.is_the_cutest

Bases: Check

Fails if you aren’t Jaxtar.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

commands

Module containing all Command related objects.

class yami.commands.MessageCommand(callback: Callable[[...], Any], name: str, description: str, *, aliases: Iterable[str], raise_conversion: bool, parent: Optional[MessageCommand] = None, invoke_with: bool = False)

Bases: object

An object that represents a message content command.

Note

You should not instantiate this class manually, instead use:

The command decorator inside a Module subclass.
The yami.Bot.command decorator outside a Module.

Parameters

callback (typing.Callable […, typing.Any]) – The async callback function for the command.
name (str) – The name of the command.
description (str) – The description for the command.

Keyword Arguments

aliases (typing.Iterable [str]) – The aliases for the command.
raise_conversion (bool) – Whether or not to raise an error when a type hint conversion for the command arguments fails.
parent (MessageCommand | None) – The parent of this command if it is a subcommand, or None if not.
invoke_with (bool) – Whether or not to invoke this command with its subcommands, if it has any. Defaults to False.

property aliases: Iterable[str]: The aliases for the command.

property checks: dict[str, yami.checks.Check]: A dictionary containing name, Check pairs that are registered to this command.

property name: str: The name of the command.

property module: yami.modules.Module | None: The Module this command originates from, if any.

property description: str: The commands description.

property callback: Callable[[...], Any]: The callback function registered to this command.

property raise_conversion: bool: Whether or not to raise an error when a type hint conversion for the command arguments fails.

property was_globally_added: bool: True if this command was created with the command decorator, and False if not.

property subcommands: dict[str, yami.commands.MessageCommand]: A dictionary containing name, MessageCommand pairs that are registered to this command.

property is_subcommand: bool: Whether or not this command is a subcommand.

property parent: yami.commands.MessageCommand | None: The parent of this command, or None if this command is not a subcommand.

property invoke_with: bool: Whether or not to invoke this command if one of its subcommands are invoked.

add_check(check: Union[Type[Check], Check]) → Check

Adds a check to be run before this command.

Parameters: check (Check) – The check to add.
Returns: The check that was added.
Return type: Check
Raises: CheckAddFailed – If the check is not a Check object.

remove_check(check: Union[Type[Check], Check]) → yami.checks.Check | None

Removes a check from this command. If this check is not bound to this command, it will do nothing.

Parameters: check (Check) – The check to remove.
Returns: The removed check, or none if it was not found.
Return type: Check | None
Raises: CheckRemovalFailed – When an invalid type is passed as an argument to this method.

add_subcommand(command: Union[Callable[[...], Any], MessageCommand], *, name: Optional[str] = None, description: str = '', aliases: list[str] | tuple[str, ...] = [], raise_conversion: bool = False) → MessageCommand

Adds a subcommand to the command.

Parameters

command (typing.Callable […, typing.Any] | yami.MessageCommand) – The subcommand to add.

Keyword Arguments

name (str | None) – The name of the subcommand. (defaults to the function name)
description (str) – The subcommands description. (defaults to "")
aliases (typing.Iterable [str]) – The subcommands aliases (defaults to [])
raise_conversion (bool) – Whether or not to raise an error when argument conversion fails. (Defaults to False)

Returns

The subcommand that was added.

Return type

Raises

DuplicateCommand – If the subcommand shares a name or alias with an existing subcommand.
TypeError – If aliases is not a list or a tuple.

iter_checks() → Generator[Check, None, None]

Iterates the commands checks.

Returns: A generator over the checks.
Return type: Generator
Yields: Check – Each check.

iter_subcommands() → Generator[MessageCommand, None, None]

Iterates the subcommands for this command.

Returns: A generator over the subcommands.
Return type: Generator
Yields: MessageCommand – Each subcommand.

subcommand(name: Optional[str] = None, description: str = '', *, aliases: Iterable[str] = [], raise_conversion: bool = False, invoke_with: bool = False) → Callable[[...], MessageCommand]

Decorator to add a subcommand to an existing command. It should decorate the callback that should fire when this subcommand is run.

Parameters

name (str) – The name of the subcommand. Defaults to the function name.
description (str) – The subcommand description. If omitted, the callbacks docstring will be used instead.

Keyword Arguments

aliases (Iterable [str]) – A list or tuple of aliases for the command.
raise_conversion (bool) – Whether or not to raise ConversionFailed when converting a commands argument fails.
invoke_with (bool) – Whether or not to invoke this commands callback, when its subcommand is invoked.

Returns

A message command crafted from the callback, and decorator arguments.

Return type

yami.commands.command(name: Optional[str] = None, description: str = '', *, aliases: Iterable[str] = [], raise_conversion: bool = False, invoke_with: bool = False) → Callable[[...], MessageCommand]

Decorator to add commands to the bot inside of modules. It should decorate the callback that should fire when this command is run.

Parameters

name (str) – The name of the command. Defaults to the function name.
description (str) – The command description. If omitted, the callbacks docstring will be used instead.

Keyword Arguments

aliases (Iterable [str]) – A list or tuple of aliases for the command.
raise_conversion (bool) – Whether or not to raise ConversionFailed when converting a commands argument fails.
invoke_with (bool) – Whether or not to invoke this commands callback, when its subcommand is invoked.

Returns

A message command crafted from the callback, and decorator arguments.

Return type

Callable […, yami.MessageCommand]

context

Module containing Context objects.

class yami.context.Context(bot: Bot, message: Message, command: MessageCommand, prefix: str, invoked_subcommands: list[yami.commands.MessageCommand] = [])

Bases: ABC

Base Context all Yami contexts inherit from.

abstract property bot: Bot: The bot instance associated with this context.

abstract property author: User: The user that created this context.

abstract property cache: Cache: Shortcut to the bots cache.

abstract property rest: RESTClient: Shortcut to the bots rest client.

abstract property guild_id: hikari.snowflakes.Snowflake | None: The guild id associated with the context, or None if this context was a DMChannel.

abstract property args: list[yami.args.MessageArg]: A list of converted MessageArgs passed to this context. Context will not be present here even though it was passed to the command callback.

Note

If this context was invoked with subcommands and parent commands, only the final subcommands args will be present here.

abstract property exceptions: list[Exception]: Any exceptions that were generated when this context was created, including failed check exceptions.

abstract property channel_id: Snowflake: The channel id this context was created in.

abstract property message: Message: The message associated with this context.

abstract property message_id: Snowflake: The message id of this contexts message.

abstract property content: str: The content of the message associated with the context.

abstract property command: MessageCommand: The command invoked during the creation of this context.

abstract property shared: Shared: A Shared object that can be used to share data between subcommands.

Hint

Also houses cached data from the checks that were run for this context.

class yami.context.MessageContext(bot: Bot, message: Message, command: MessageCommand, prefix: str, invoked_subcommands: list[yami.commands.MessageCommand] = [])

Bases: Context

The context surrounding a message commands invocation.

Parameters

bot (Bot) – The bot instance associated with the context.
message (hikari.Message) – The message that created this context.
command (yami.MessageCommand) – The command that was invoked to create this context.
prefix (str) – The prefix that was used to create this context.

property bot: Bot: The bot instance associated with this context.

property author: User: The user that created this context.

property cache: Cache: Shortcut to the bots cache.

property rest: RESTClient: Shortcut to the bots rest client.

property guild_id: hikari.snowflakes.Snowflake | None: The guild id associated with the context, or None if this context was a DMChannel.

property args: list[yami.args.MessageArg]: A list of converted MessageArgs passed to this context. Context will not be present here even though it was passed to the command callback.

Note

If this context was invoked with subcommands and parent commands, only the final subcommands args will be present here.

property exceptions: list[Exception]: Any exceptions that were generated when this context was created, including failed check exceptions.

property channel_id: Snowflake: The channel id this context was created in.

property message: Message: The message associated with this context.

property message_id: Snowflake: The message id of this contexts message.

property content: str: The content of the message associated with the context.

property command: MessageCommand: The command invoked during the creation of this context.

property prefix: str: The prefix used to create this context.

property shared: Shared: A Shared object that can be used to share data between subcommands.

Hint

Also houses cached data from the checks that were run for this context.

property invoked_subcommands: list[yami.commands.MessageCommand]: The subcommands that were invoked with this context, or None if there were none.

Note

If subcommands were chained and the parent callback was not actually run (due to having invoke_with set to False) it will not appear here.

trigger_typing() → special_endpoints.TypingIndicator

Shortcut method to ctx.rest.trigger_typing in the current channel.

async with ctx.trigger_typing():
    # do work here and typing will stop
    # when the context manager is exited.

Returns: An async context manager for the typing indicator on Discord.
Return type: TypingIndicator

iter_arg_values() → Generator[Any, None, None]

Iterates the contexts message args.

Returns: A generator over the arguments.
Return type: Generator
Yields: Any – Each argument.

async respond(content: Union[Any, UndefinedType], *, delete_after: Optional[int] = None, **kwargs: Any) → Message

Respond to the message that created this context.

Parameters

content (Any) – The content of this response.

Keyword Arguments

delete_after (int | None) – The optional length of time to delete this message after (in seconds).
**kwargs (Any) – The remaining kwargs passed to the hikari.Message.respond method.

Returns

The message this response created.

Return type

Message

async getch_member() → hikari.guilds.Member | None

Get or fetch the hikari.Member object associated with the context. This method calls to the cache first, and falls back to rest if not found.

Warning

This method can utilize both cache, and rest. For more fine grained control consider using cache or rest yourself explicitly.

Returns: The member object associated with this context, or None if the context is a DMChannel.
Return type: Member | None

async getch_guild() → hikari.guilds.Guild | None

Get or fetch the hikari.guilds.Guild object associated with the context. This method calls to the cache first, and falls back to rest if not found.

Warning

This method can utilize both cache, and rest. For more fine grained control consider using cache or rest yourself explicitly.

Returns: The guild object associated with this context, or None if the context is a DMChannel.
Return type: Guild | None

async getch_channel() → hikari.channels.GuildChannel | hikari.channels.PartialChannel

Get or fetch the hikari.channels.PartialChannel object associated with the context. This method calls to the cache first, and falls back to rest if not found.

Note

This method can return any of the following:

DMChannel, GroupDMChannel, GuildTextChannel, GuildVoiceChannel, GuildStoreChannel, GuildNewsChannel.

Warning

This method can utilize both cache, and rest. For more fine grained control consider using cache or rest yourself explicitly.

Returns: The channel object associated with this context.
Return type: PartialChannel

converters

Module containing the Yami converters.

class yami.converters.Converter(value: Any)

Bases: ABC

Base class all Yami converters inherit from.

class yami.converters.BuiltinConverter(value: Any)

Bases: Converter

Converts to the builtin types.

Parameters: value (Any) – The value to perform the conversion on.

classmethod can_convert(type_: Any) → bool

Whether or not this converter can convert an object to this type.

Parameters: type (Any) – The type to check compatibility for.
Returns: True if it can be converted.
Return type: bool

as_type(type_: BuiltinTypeT, *, encoding: str = 'utf8') → BuiltinTypeT

Converts the value to the given type.

Parameters: type (BuiltinTypeT) – The type to try converting to.
Keyword Arguments: encoding (str) – The encoding if type_ is bytes. Defaults to "utf8".
Returns: The converted value.
Return type: BuiltinTypeT
Raises: ConversionFailed – If the conversion fails for any reason.

as_bool() → bool

Converts the value to bool.

Hint

'true' and 'True' will be True
'false' and 'False' will be False

Returns: The converted value.
Return type: bool
Raises: ConversionFailed – If the conversion fails for any reason.

as_str() → str

Converts the value to str.

Returns: The converted value.
Return type: str
Raises: ConversionFailed – If the conversion fails for any reason.

as_bytes(encoding: str = 'utf8') → bytes

Converts the value to bytes.

Parameters: encoding (str) – The encoding to use. Defaults to "utf8".
Returns: The converted value.
Return type: bytes
Raises: ConversionFailed – If the conversion fails for any reason.

as_int() → int

Converts the value to int.

Returns: The converted value.
Return type: int
Raises: ConversionFailed – If the conversion fails for any reason.

as_complex() → complex

Converts to complex.

Returns: The converted value.
Return type: complex
Raises: ConversionFailed – If the conversion fails for any reason.

as_float() → float

Converts the value to float.

Returns: The converted value.
Return type: float
Raises: ConversionFailed – If the conversion fails for any reason.

class yami.converters.HikariConverter

Bases: Converter

Converts to the hikari types.

Warning

Not yet implemented!

events

Module for Yami events.

class yami.events.YamiEvent

Bases: Event, ABC

The base class all Yami events inherit from.

abstract property app: Bot

App instance for this application.

Returns: The REST-aware app trait.
Return type: hikari.traits.RESTAware

class yami.events.CommandInvokeEvent(ctx: Context)

Bases: YamiEvent

Fires when any command is invoked.

property app: Bot: The app (Bot) associated with this event.

property bot: Bot: The app (Bot) associated with this event.

property ctx: Context: The context this event is attached to.

property command: MessageCommand: The command that triggered this event.

class yami.events.CommandExceptionEvent(ctx: Context)

Bases: YamiEvent

Fires when a command encounters an exception of any kind.

property app: Bot: The app (Bot) associated with this event.

property bot: Bot: The app (Bot) associated with this event.

property ctx: Context: The context this event is attached to.

property command: MessageCommand: The command that triggered this event.

property exceptions: list[Exception]: The exception that triggered this event.

class yami.events.CommandSuccessEvent(ctx: Context)

Bases: YamiEvent

Fires when any command invocation is successful.

property app: Bot: The app (Bot) associated with this event.

property bot: Bot: The app (Bot) associated with this event.

property ctx: Context: The context this event is attached to.

property command: MessageCommand: The command that triggered this event.

exceptions

Yami exceptions.

exception yami.exceptions.YamiException

Bases: Exception

Base exception all Yami exceptions inherit from.

exception yami.exceptions.CommandException

Bases: YamiException

Raised when an exception relating to a command occurs.

exception yami.exceptions.CommandNotFound

Raised when a command is invoked, or attempted to be accessed but no command with that name is found.

exception yami.exceptions.BadArgument

Raised when a bad argument is passed to a message command.

exception yami.exceptions.DuplicateCommand

Raised when a command is added that shares a name or aliases with an existing command, or subcommand on the same level.

exception yami.exceptions.ModuleException

Bases: YamiException

Raised when an error associated with a module occurs.

exception yami.exceptions.ModuleRemoveException

Raised when a module fails to be removed from the bot.

exception yami.exceptions.ModuleAddException

Raised when a module fails to be added to the bot.

exception yami.exceptions.ModuleLoadException

Raised when a module fails to be loaded to the bot.

exception yami.exceptions.ModuleUnloadException

Raised when a module fails to be unloaded from the bot.

exception yami.exceptions.CheckException

Raised when an exception relating to a check occurs.

exception yami.exceptions.BadCheck

Bases: CheckException

Raised when a check decorator is placed below the command decorator, or otherwise used incorrectly.

exception yami.exceptions.CheckRemovalFailed

Bases: CheckException

Raised when an invalid type is passed to remove_check.

exception yami.exceptions.CheckFailed

Bases: CheckException

Raised when a check is failed during command invocation.

exception yami.exceptions.CheckAddFailed

Bases: CheckException

Raised when an invalid type is passed to add_check.

exception yami.exceptions.ListenerException

Bases: YamiException

Raised when an exception occurs relating to a module listener.

exception yami.exceptions.TooManyArgs

Raised when too many arguments are passed to a command.

exception yami.exceptions.MissingArgs

Raised when a command is run, but not all args are supplied.

exception yami.exceptions.ConversionFailed

Bases: YamiException

Raised when the conversion performed by a converter fails.

modules

Houses the Yami Module system.

class yami.modules.Module(bot: Bot)

Bases: object

A collection of commands and functions that typically share a need for the same data, or are related in some way.

Parameters: bot (Bot) – The bot instance.

Hint

You should subclass Module to create your own modules.
Modules do not require any special functions in their file.
Modules are loaded via the load_module and load_all_modules methods.

Warning

If you overwrite the __init__ method, it should take only 1 argument which is of type Bot.

class MyMod(yami.Module):
    def __init__(self, bot: yami.Bot) -> None:
        super().__init__(bot)
        # Do whatever else you need here.

property name: str: The name of this module.

property bot: Bot: The bot this module belongs to.

property commands: dict[str, yami.commands.MessageCommand]: A dictionary of name, MessageCommand pairs this module contains.

property description: str: The description of this module.

property is_loaded: bool: Whether or not this module is currently loaded.

iter_commands() → Generator[MessageCommand, None, None]

Iterates the modules commands.

Returns: A generator over the commands.
Return type: Generator
Yields: MessageCommand – Each command.

add_command(command: MessageCommand) → None

Adds a command to the module.

Parameters: command (MessageCommand) – The command to add.
Raises: DuplicateCommand – When a command with this name already exists.

remove_command(name: str) → MessageCommand

Removes a command from the module.

Parameters: name (str) – The name of the command to remove. (case sensitive)
Returns: The command that was removed.
Return type: MessageCommand
Raises: CommandNotFound – When a command with this name is not found.

Full API

class yami.Bot(token: str, prefix: Union[str, Sequence[str]], *, owner_ids: Sequence[int] = (), allow_extra_args: bool = False, raise_cmd_not_found: bool = False, **kwargs: Any)

Bases: GatewayBot

A subclass of GatewayBot that provides an interface for handling commands.

This is the class you will instantiate to utilize command features on top of the GatewayBot superclass.

Warning

This class is slotted, if you want to set your own custom properties you have 2 choices:

Use the Bot.shared property which is an instance of Shared.
Subclass Bot, but this can lead to issues if you overwrite private or public attributes in your subclass.

Parameters

token (str) – The bot token to sign in with.
prefix (str | Sequence [str]) – The prefix, or sequence of prefixes to listen for. Planned support for mentions, and functions soon (tm).

Keyword Arguments

owner_ids (Sequence [int]) – A sequence of integers representing the Snowflakes of the bots owners. Defaults to ().
allow_extra_args (bool) – Whether or not the bot should allow extra args in command invocations. Defaults to False.
raise_cmd_not_found (bool) – Whether or not to raise the CommandNotFound exception. Defaults to False.
**kwargs (Any) – The remaining kwargs for GatewayBot.

property commands: dict[str, yami.commands.MessageCommand]: A dictionary of name, MessageCommand pairs bound to the bot, including commands from any loaded modules.

property aliases: dict[str, str]: A dictionary of aliases to their corresponding MessageCommand name.

property modules: dict[str, yami.modules.Module]: A dictionary of name, Module pairs that are added to the bot, this includes unloaded modules.

property owner_ids: Sequence[int]: A sequence of integers representing the ids of the bots owners.

property allow_extra_args: bool: If True do not error when extra args are passed to a command.

property shared: Shared: The Shared instance associated with this bot.

property raise_cmd_not_found: bool: Returns True if this bot will raise a CommandNotFound exception when a prefix is used, but no command was found.

load_all_modules(*paths: str | pathlib.Path, recursive: bool = True) → None

Loads all modules from each of the given paths.

Note

This method looks for all .py files that do not begin with an _. It is recursive by default.

If this method fails partway through, the bots modules are reverted to their previous state and no modules will be loaded.

Parameters

*paths (str | Path) – One or more paths to load modules from.

Keyword Arguments

recursive (bool) – Whether or not to recurse into sub directories while loading modules.

Raises

ModuleLoadException – When a module with the same name is already loaded on the bot, or when the named module is not found inside the given path’s source file.
ModuleAddException – When there is a failure with one of the commands in the module.

load_module(name: str, path: str | pathlib.Path) → None

Loads a single module class from the path specified.

Note

If this method fails partway through, the bots modules are reverted to their previous state and the module will not be loaded.

Parameters

name (str) – The name of the module class to load. (case sensitive)
path (str | Path) – The path to load the module from.

Raises

ModuleLoadException – When a module with the same name is already loaded on the bot, or when the named module is not found inside the given paths source file.
ModuleAddException – When there is a failure with one of the commands in the module.

unload_module(name: str) → Module

Unloads a single module class with the given name. It will remain in Bot.modules, but just in an unloaded state and its commands will no longer be executable until it is loaded again.

Parameters: name (str) – The name of the module class to unload. (case sensitive)
Returns: The module that was unloaded.
Return type: Module
Raises: ModuleUnloadException – When no module with this name was found.

remove_module(name: str) → Module

Removes a single module class with the given name. It will no longer be accessible via Bot.modules.

Parameters: name (str) – The name of the module class to remove. (case sensitive)
Returns: The module that was removed.
Return type: Module
Raises: ModuleRemoveException – When no module with this name was found.

add_command(command: Union[Callable[[...], Any], MessageCommand], *, name: Optional[str] = None, description: str = '', aliases: list[str] | tuple[str, ...] = [], raise_conversion: bool = False) → MessageCommand

Adds a command to the bot.

Parameters

command (Callable […, Any] | MessageCommand) – The command or callback to add.

Keyword Arguments

name (str | None) – The name of the command. Defaults to the function name.
description (str) – The commands description. Defaults to "".
aliases (Iterable [str]) – The commands aliases. Defaults to [].
raise_conversion (bool) – Whether or not to raise an exception if argument conversion fails. Defaults to False.

Returns

The command that was added.

Return type

Raises

DuplicateCommand – If the command shares a name or alias with an existing command.
TypeError – If aliases is not a list or a tuple.

remove_command(name: str) → MessageCommand

Removes a MessageCommand from the Bot, and its yami.Module if it has one.

Parameters: name (str) – The name of the command to remove.
Returns: The command that was removed.
Return type: MessageCommand
Raises: CommandNotFound – When the command was not found.

iter_commands() → Generator[MessageCommand, None, None]

Iterates the bots commands.

Returns: A generator over the commands.
Return type: Generator
Yields: MessageCommand – Each command.

iter_modules() → Generator[Module, None, None]

Iterates over the modules attached to the bot. This will included both loaded and unloaded modules.

Returns: A generator over the modules.
Return type: Generator
Yields: Module – Each module.

iter_loaded_modules() → Generator[Module, None, None]

Iterates over the modules attached to the bot. This will only include loaded modules.

Returns: A generator over the modules.
Return type: Generator
Yields: Module – Each loaded module.

get_command(name: str) → yami.commands.MessageCommand | None

Gets a command.

Parameters: name (str) – The name or alias of the command to get.
Returns: The command, or None if not found.
Return type: MessageCommand | None

get_module(name: str) → yami.modules.Module | None

Gets a module.

Parameters: name (str) – The name of the module to get.
Returns: The module, or None if not found.
Return type: yami.Module | None

command(name: Optional[str] = None, description: str = '', *, aliases: Sequence[str] = (), raise_conversion: bool = False, invoke_with: bool = False) → Callable[[...], Any]

Decorator to add a MessageCommand to the bot. This should be placed immediately above the command callback. Any checks should be placed above this decorator.

Parameters

name (str) – The name of the command. Defaults to the function name.
description (str) – The command description. If omitted, the callbacks docstring will be used instead.

Keyword Arguments

aliases (Sequence [str]) – A list or tuple of aliases for the command.
raise_conversion (bool) – Whether or not to raise an exception when a type hint conversion for the command arguments fails.

Returns

A message command crafted from the callback, and decorator arguments.

Return type

class yami.MessageContext(bot: Bot, message: Message, command: MessageCommand, prefix: str, invoked_subcommands: list[yami.commands.MessageCommand] = [])

Bases: Context

The context surrounding a message commands invocation.

Parameters

bot (Bot) – The bot instance associated with the context.
message (hikari.Message) – The message that created this context.
command (yami.MessageCommand) – The command that was invoked to create this context.
prefix (str) – The prefix that was used to create this context.

property bot: Bot: The bot instance associated with this context.

property author: User: The user that created this context.

property cache: Cache: Shortcut to the bots cache.

property rest: RESTClient: Shortcut to the bots rest client.

property guild_id: hikari.snowflakes.Snowflake | None: The guild id associated with the context, or None if this context was a DMChannel.

property args: list[yami.args.MessageArg]: A list of converted MessageArgs passed to this context. Context will not be present here even though it was passed to the command callback.

Note

If this context was invoked with subcommands and parent commands, only the final subcommands args will be present here.

property exceptions: list[Exception]: Any exceptions that were generated when this context was created, including failed check exceptions.

property channel_id: Snowflake: The channel id this context was created in.

property message: Message: The message associated with this context.

property message_id: Snowflake: The message id of this contexts message.

property content: str: The content of the message associated with the context.

property command: MessageCommand: The command invoked during the creation of this context.

property prefix: str: The prefix used to create this context.

property shared: Shared: A Shared object that can be used to share data between subcommands.

Hint

Also houses cached data from the checks that were run for this context.

property invoked_subcommands: list[yami.commands.MessageCommand]: The subcommands that were invoked with this context, or None if there were none.

Note

If subcommands were chained and the parent callback was not actually run (due to having invoke_with set to False) it will not appear here.

trigger_typing() → special_endpoints.TypingIndicator

Shortcut method to ctx.rest.trigger_typing in the current channel.

async with ctx.trigger_typing():
    # do work here and typing will stop
    # when the context manager is exited.

Returns: An async context manager for the typing indicator on Discord.
Return type: TypingIndicator

iter_arg_values() → Generator[Any, None, None]

Iterates the contexts message args.

Returns: A generator over the arguments.
Return type: Generator
Yields: Any – Each argument.

async respond(content: Union[Any, UndefinedType], *, delete_after: Optional[int] = None, **kwargs: Any) → Message

Respond to the message that created this context.

Parameters

content (Any) – The content of this response.

Keyword Arguments

delete_after (int | None) – The optional length of time to delete this message after (in seconds).
**kwargs (Any) – The remaining kwargs passed to the hikari.Message.respond method.

Returns

The message this response created.

Return type

Message

async getch_member() → hikari.guilds.Member | None

Get or fetch the hikari.Member object associated with the context. This method calls to the cache first, and falls back to rest if not found.

Warning

This method can utilize both cache, and rest. For more fine grained control consider using cache or rest yourself explicitly.

Returns: The member object associated with this context, or None if the context is a DMChannel.
Return type: Member | None

async getch_guild() → hikari.guilds.Guild | None

Get or fetch the hikari.guilds.Guild object associated with the context. This method calls to the cache first, and falls back to rest if not found.

Warning

This method can utilize both cache, and rest. For more fine grained control consider using cache or rest yourself explicitly.

Returns: The guild object associated with this context, or None if the context is a DMChannel.
Return type: Guild | None

async getch_channel() → hikari.channels.GuildChannel | hikari.channels.PartialChannel

Get or fetch the hikari.channels.PartialChannel object associated with the context. This method calls to the cache first, and falls back to rest if not found.

Note

This method can return any of the following:

DMChannel, GroupDMChannel, GuildTextChannel, GuildVoiceChannel, GuildStoreChannel, GuildNewsChannel.

Warning

This method can utilize both cache, and rest. For more fine grained control consider using cache or rest yourself explicitly.

Returns: The channel object associated with this context.
Return type: PartialChannel

class yami.MessageCommand(callback: Callable[[...], Any], name: str, description: str, *, aliases: Iterable[str], raise_conversion: bool, parent: Optional[MessageCommand] = None, invoke_with: bool = False)

Bases: object

An object that represents a message content command.

Note

You should not instantiate this class manually, instead use:

The command decorator inside a Module subclass.
The yami.Bot.command decorator outside a Module.

Parameters

callback (typing.Callable […, typing.Any]) – The async callback function for the command.
name (str) – The name of the command.
description (str) – The description for the command.

Keyword Arguments

aliases (typing.Iterable [str]) – The aliases for the command.
raise_conversion (bool) – Whether or not to raise an error when a type hint conversion for the command arguments fails.
parent (MessageCommand | None) – The parent of this command if it is a subcommand, or None if not.
invoke_with (bool) – Whether or not to invoke this command with its subcommands, if it has any. Defaults to False.

property aliases: Iterable[str]: The aliases for the command.

property checks: dict[str, yami.checks.Check]: A dictionary containing name, Check pairs that are registered to this command.

property name: str: The name of the command.

property module: yami.modules.Module | None: The Module this command originates from, if any.

property description: str: The commands description.

property callback: Callable[[...], Any]: The callback function registered to this command.

property raise_conversion: bool: Whether or not to raise an error when a type hint conversion for the command arguments fails.

property was_globally_added: bool: True if this command was created with the command decorator, and False if not.

property subcommands: dict[str, yami.commands.MessageCommand]: A dictionary containing name, MessageCommand pairs that are registered to this command.

property is_subcommand: bool: Whether or not this command is a subcommand.

property parent: yami.commands.MessageCommand | None: The parent of this command, or None if this command is not a subcommand.

property invoke_with: bool: Whether or not to invoke this command if one of its subcommands are invoked.

add_check(check: Union[Type[Check], Check]) → Check

Adds a check to be run before this command.

Parameters: check (Check) – The check to add.
Returns: The check that was added.
Return type: Check
Raises: CheckAddFailed – If the check is not a Check object.

remove_check(check: Union[Type[Check], Check]) → yami.checks.Check | None

Removes a check from this command. If this check is not bound to this command, it will do nothing.

Parameters: check (Check) – The check to remove.
Returns: The removed check, or none if it was not found.
Return type: Check | None
Raises: CheckRemovalFailed – When an invalid type is passed as an argument to this method.

add_subcommand(command: Union[Callable[[...], Any], MessageCommand], *, name: Optional[str] = None, description: str = '', aliases: list[str] | tuple[str, ...] = [], raise_conversion: bool = False) → MessageCommand

Adds a subcommand to the command.

Parameters

command (typing.Callable […, typing.Any] | yami.MessageCommand) – The subcommand to add.

Keyword Arguments

name (str | None) – The name of the subcommand. (defaults to the function name)
description (str) – The subcommands description. (defaults to "")
aliases (typing.Iterable [str]) – The subcommands aliases (defaults to [])
raise_conversion (bool) – Whether or not to raise an error when argument conversion fails. (Defaults to False)

Returns

The subcommand that was added.

Return type

Raises

DuplicateCommand – If the subcommand shares a name or alias with an existing subcommand.
TypeError – If aliases is not a list or a tuple.

iter_checks() → Generator[Check, None, None]

Iterates the commands checks.

Returns: A generator over the checks.
Return type: Generator
Yields: Check – Each check.

iter_subcommands() → Generator[MessageCommand, None, None]

Iterates the subcommands for this command.

Returns: A generator over the subcommands.
Return type: Generator
Yields: MessageCommand – Each subcommand.

subcommand(name: Optional[str] = None, description: str = '', *, aliases: Iterable[str] = [], raise_conversion: bool = False, invoke_with: bool = False) → Callable[[...], MessageCommand]

Decorator to add a subcommand to an existing command. It should decorate the callback that should fire when this subcommand is run.

Parameters

name (str) – The name of the subcommand. Defaults to the function name.
description (str) – The subcommand description. If omitted, the callbacks docstring will be used instead.

Keyword Arguments

aliases (Iterable [str]) – A list or tuple of aliases for the command.
raise_conversion (bool) – Whether or not to raise ConversionFailed when converting a commands argument fails.
invoke_with (bool) – Whether or not to invoke this commands callback, when its subcommand is invoked.

Returns

A message command crafted from the callback, and decorator arguments.

Return type

class yami.Module(bot: Bot)

Bases: object

A collection of commands and functions that typically share a need for the same data, or are related in some way.

Parameters: bot (Bot) – The bot instance.

Hint

You should subclass Module to create your own modules.
Modules do not require any special functions in their file.
Modules are loaded via the load_module and load_all_modules methods.

Warning

If you overwrite the __init__ method, it should take only 1 argument which is of type Bot.

class MyMod(yami.Module):
    def __init__(self, bot: yami.Bot) -> None:
        super().__init__(bot)
        # Do whatever else you need here.

property name: str: The name of this module.

property bot: Bot: The bot this module belongs to.

property commands: dict[str, yami.commands.MessageCommand]: A dictionary of name, MessageCommand pairs this module contains.

property description: str: The description of this module.

property is_loaded: bool: Whether or not this module is currently loaded.

iter_commands() → Generator[MessageCommand, None, None]

Iterates the modules commands.

Returns: A generator over the commands.
Return type: Generator
Yields: MessageCommand – Each command.

add_command(command: MessageCommand) → None

Adds a command to the module.

Parameters: command (MessageCommand) – The command to add.
Raises: DuplicateCommand – When a command with this name already exists.

remove_command(name: str) → MessageCommand

Removes a command from the module.

Parameters: name (str) – The name of the command to remove. (case sensitive)
Returns: The command that was removed.
Return type: MessageCommand
Raises: CommandNotFound – When a command with this name is not found.

class yami.Shared

Bases: object

Represents data container for shared storage.

An instance of Shared is stored on each context, and on the bot.

Feel free to examine this in your own contexts, and even store things in one on your bot. You can instantiate a Shared anywhere you want, in fact.

You can dynamically add attributes to the shared object.

s = yami.Shared()
s.hello = "hello"
s.hello # returns "hello"
s.doesnt_exist # returns yami.SharedNone

property items: dict[str, Any]: A dictionary of attribute name, value pairs that have been stored inside this Shared instance.

has(name: str) → bool

Checks whether the Shared instance contains an attribute with the given name. If so, you can assume the attribute will not return a SharedNone.

Args

name: str: The name of the attribute to check for.

Returns

bool: True if the attribute exists, otherwise False.

class yami.SharedNone

Bases: object

The type returned from Shared if an attribute is not set, this class can not be instantiated.

When a SharedNone is returned, it is this class, but its type() will be YamiNoneType.
To check if a value returned by Shared was SharedNone use shared.obj is SharedNone.

class yami.YamiNoneType

Bases: type

Metaclass for SharedNone.

class yami.MessageArg(param: Parameter, value: str)

Bases: object

Represents a MessageCommand argument.

Parameters

param (inspect.Parameter) – The raw inspect parameter.
value (str) – The value for this argument.

Warning

This class should not be instantiated manually, it will be injected during argument conversion when commands are invoked.

property name: str: The name of this arg as it appears in the callback.

property value: Any: The value for this arg, whether or not it has been converted.

property annotation: Any: The typing annotation for this arg.

property kind: _ParameterKind: The parameter kind this arg is.

property is_empty: bool: Returns True if the argument had no type hints.

property is_converted: bool: Whether or not this argument has been converted yet.

async convert(ctx: context.MessageContext) → None

Attempts to convert the argument to its type hint.

Parameters: ctx (MessageContext) – The message context.

class yami.Converter(value: Any)

Bases: ABC

Base class all Yami converters inherit from.

class yami.BuiltinConverter(value: Any)

Bases: Converter

Converts to the builtin types.

Parameters: value (Any) – The value to perform the conversion on.

classmethod can_convert(type_: Any) → bool

Whether or not this converter can convert an object to this type.

Parameters: type (Any) – The type to check compatibility for.
Returns: True if it can be converted.
Return type: bool

as_type(type_: BuiltinTypeT, *, encoding: str = 'utf8') → BuiltinTypeT

Converts the value to the given type.

Parameters: type (BuiltinTypeT) – The type to try converting to.
Keyword Arguments: encoding (str) – The encoding if type_ is bytes. Defaults to "utf8".
Returns: The converted value.
Return type: BuiltinTypeT
Raises: ConversionFailed – If the conversion fails for any reason.

as_bool() → bool

Converts the value to bool.

Hint

'true' and 'True' will be True
'false' and 'False' will be False

Returns: The converted value.
Return type: bool
Raises: ConversionFailed – If the conversion fails for any reason.

as_str() → str

Converts the value to str.

Returns: The converted value.
Return type: str
Raises: ConversionFailed – If the conversion fails for any reason.

as_bytes(encoding: str = 'utf8') → bytes

Converts the value to bytes.

Parameters: encoding (str) – The encoding to use. Defaults to "utf8".
Returns: The converted value.
Return type: bytes
Raises: ConversionFailed – If the conversion fails for any reason.

as_int() → int

Converts the value to int.

Returns: The converted value.
Return type: int
Raises: ConversionFailed – If the conversion fails for any reason.

as_complex() → complex

Converts to complex.

Returns: The converted value.
Return type: complex
Raises: ConversionFailed – If the conversion fails for any reason.

as_float() → float

Converts the value to float.

Returns: The converted value.
Return type: float
Raises: ConversionFailed – If the conversion fails for any reason.

class yami.HikariConverter

Bases: Converter

Converts to the hikari types.

Warning

Not yet implemented!

class yami.Check

Bases: ABC

Base class all Yami checks inherit from.

classmethod get_name() → str

Returns the name of this Check subclass.

Returns: The name of the class.
Return type: str

abstract async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.is_owner

Bases: Check

Fails if the author of the command is not the bots owner.

Hint

Who is the bots owner?

Any user with an id matching one of the ids passed into the bots constructor for the kwarg owner_ids.
The application owner fetched from Discord if no owner_ids were passed to the constructor.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.is_in_guild

Bases: Check

Fails if the command was not run in a guild.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.is_in_dm

Bases: Check

Fails if the command was not run in a DM.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.has_roles(*roles: str | int)

Bases: Check

Fails if the author does not have all of the roles passed to this check decorator.

This is inherently an is_in_guild check as well, because a user cannot have a role outside of a guild.

Parameters: *roles (str | int) – The name or id of the role or roles the user must have.
Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.has_any_role(*roles: str | int)

Bases: Check

Fails if the author does not have any of the role names or ids passed to this check.

This is inherently an is_in_guild check as well, because a user cannot have a role outside of a guild.

Parameters: *roles (str | int) – The names or ids of the roles the user must have at least one of.
Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.has_perms(**perms: bool)

Bases: Check

Fails if the author does not have all of the specified permissions. This accumulates all permissions the user has.

This is inherently an is_in_guild check as well, because a user cannot have a role outside of a guild.

Warning

If you pass something like manage_messages=False to this check, it will do nothing.

It will not require the user to have the permission. Make sure you use manage_messages=True.

Keyword Arguments

**perms (bool) –

Keyword arguments for each of the available hikari perms.

Raises

CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.custom_check(check: Union[Callable[[MessageContext], Any], Check], *, message: str = '')

Bases: Check

A custom check.

Hint

If the check returns False or raises an Exception the check will fail.
If the check returns True or any other value without raising an error, it will pass.

Parameters

check (Callable [[MessageContext], Any]) –

The callback function that should be used for the check.

Note

It should accept one argument of type MessageContext and return False or raise an error if it fails.
This can be an async, or sync function.

Keyword Arguments

message – (str): The optional message to use in the CheckFailed exception. The default message is "a custom check was failed".

Raises

CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

class yami.is_the_cutest

Bases: Check

Fails if you aren’t Jaxtar.

Raises: CheckFailed – When the check fails.

async execute(ctx: MessageContext) → None

Executes the check.

Parameters: ctx (MessageContext) – The context to execute the check against.
Raises: CheckFailed – When the check fails.

yami.command(name: Optional[str] = None, description: str = '', *, aliases: Iterable[str] = [], raise_conversion: bool = False, invoke_with: bool = False) → Callable[[...], MessageCommand]

Decorator to add commands to the bot inside of modules. It should decorate the callback that should fire when this command is run.

Parameters

name (str) – The name of the command. Defaults to the function name.
description (str) – The command description. If omitted, the callbacks docstring will be used instead.

Keyword Arguments

aliases (Iterable [str]) – A list or tuple of aliases for the command.
raise_conversion (bool) – Whether or not to raise ConversionFailed when converting a commands argument fails.
invoke_with (bool) – Whether or not to invoke this commands callback, when its subcommand is invoked.

Returns

A message command crafted from the callback, and decorator arguments.

Return type

Callable […, yami.MessageCommand]

exception yami.YamiException

Bases: Exception

Base exception all Yami exceptions inherit from.

exception yami.CommandNotFound

Raised when a command is invoked, or attempted to be accessed but no command with that name is found.

exception yami.BadArgument

Raised when a bad argument is passed to a message command.

exception yami.DuplicateCommand

Raised when a command is added that shares a name or aliases with an existing command, or subcommand on the same level.

exception yami.ModuleException

Bases: YamiException

Raised when an error associated with a module occurs.

exception yami.ModuleRemoveException

Raised when a module fails to be removed from the bot.

exception yami.ModuleAddException

Raised when a module fails to be added to the bot.

exception yami.ModuleLoadException

Raised when a module fails to be loaded to the bot.

exception yami.ModuleUnloadException

Raised when a module fails to be unloaded from the bot.

exception yami.CheckException

Raised when an exception relating to a check occurs.

exception yami.CheckRemovalFailed

Bases: CheckException

Raised when an invalid type is passed to remove_check.

exception yami.BadCheck

Bases: CheckException

Raised when a check decorator is placed below the command decorator, or otherwise used incorrectly.

exception yami.CheckFailed

Bases: CheckException

Raised when a check is failed during command invocation.

exception yami.CheckAddFailed

Bases: CheckException

Raised when an invalid type is passed to add_check.

exception yami.ListenerException

Bases: YamiException

Raised when an exception occurs relating to a module listener.

exception yami.TooManyArgs

Raised when too many arguments are passed to a command.

exception yami.MissingArgs