Command Manager#

class ignis.command_manager.CommandManager(*args: Any, **kwargs: Any)#

A class for managing custom commands. A command is a function that accepts *args: str as args and optionally returns a str as output.

Example usage:

from ignis.command_manager import CommandManager

command_manager = CommandManager.get_default()

# Add a command
command_manager.add_command("command-name", lambda *_: "output message")
command_manager.add_command(
    "command-name", lambda fmt="%H:%M", *_: set_format(fmt)
)

# Add a command by decorator.
# "name" is optional, defaults to the function name.
@command_manager.command(name="foobar")
def foo_bar(*_) -> None:
    pass

# A regular form of callbacks
@command_manager.command(name="regular-command")
def regular_callback(
    arg1: str, arg_optional: str | None = None, *args: str
) -> str | None:
    if arg1 == "Hello":
        return "world!"

    if arg_optional:
        return f"arg_optional: {arg_optional}"

    return None # Nothing will be printed in CLI

# Remove a command by name
command_manager.remove_command("command-name")

# Run a command
command_manager.run_command("command-name")
# Run with args and output
output = command_manager.run_command("command-name", *["arg1", "arg2"])
output = command_manager.run_command("command-name", "arg1", "arg2")
# Run from the `ignis` CLI:
# $ ignis run-command command-name
# $ ignis run-command command-name arg1 arg2

# Get the callback of a command
callback = command_manager.get_command("command-name")

get_command(command_name: str) → Callable[[...], str | None]#

Get a command by name.

Parameters:: command_name (str) -- The command's name.
Return type:: Callable[..., str | None]
Returns:: The command callback.
Raises:: CommandNotFoundError -- If a command with the given name does not exist.

add_command(command_name: str, callback: Callable[[...], str | None]) → None#

Add a command.

Parameters:

command_name (str) -- The command's name.
callback (Callable[..., str | None]) -- The command callback. It accepts an *args: str and optionally returns a str.

Raises:

CommandAddedError -- If a command with the given name already exists.

Return type:

None

command(name: str | None = None)#

Returns a decorator to add a command.

Parameters:: name (str | None, default: None) -- The command's name. If not provided, the callback's name is used.

remove_command(command_name: str) → None#

Remove a command by its name.

Parameters:: command_name (str) -- The command's name.
Raises:: CommandNotFoundError -- If a command with the given name does not exist.
Return type:: None

run_command(command_name: str, *command_args: str) → str | None#

Run a command by its name.

Parameters:

command_name (str) -- The command's name.
command_args (str) -- The args list to pass to the command.

Raises:

CommandNotFoundError -- If a command with the given name does not exist.
Exception -- If the given arguments don't match the command's callback, or if the callback raises an arbitrary Exception.

Return type:

str | None

list_command_names() → tuple[str, ...]#

List the names of commands.

Return type:: tuple[str, ...]
Returns:: A tuple containing command names.

Command Manager#

This Page