cmdtools

cmdtools.base

class cmdtools.base.Cmd(text: str, prefix: str = '/', *, converter: ~typing.Type[~cmdtools.converter.converter.Converter] = <class 'cmdtools.converter.converter.Converter'>)

Bases: object

A base class for creating a command object.

Parameters:

  • text (str) – Command text to be parsed, for example: ‘/ping 8.8.8.8’

  • prefix (str) – The prefix of the command

  • converter (Converter) – Converter for arguments.

Examples

Creating a basic command object:

from cmdtools import Cmd

x = Cmd("/test")

if x.name == "test":
    print("test ok!")
property args: List[str]

List of the command’s arguments

property name: str

The name of the command if valid, otherwise return empty string

class cmdtools.base.Executor(command: Cmd, callback: Callback, *, attrs: Attributes | Dict[str, Any] | None = None)

Bases: object

A class for creating custom command executor

Parameters:

  • command (Cmd) – The command object to be executed.

  • callback (Callback) – A function that will be invoked when the command is executed.

  • attrs – Additional attributes to be passed to the callback context.

Examples

Executing a command with a custom executor:

from cmdtools import Cmd, Executor
from cmdtools.callback import callback_init

cmd = Cmd("/somecmd")

@callback_init
def some_callback(ctx):
    print("Wicked insane!")

x = Executor(cmd, some_callback)
x.exec()
Raises:

TypeError –

  • If callback is not a Callback. - If callback types do not match.

exec() → Any | None

Executes the given command

Return type:

Anything retured in the callback.

Raises:

Exception – Any exception raised during execution if error callback is not set.

async exec_coro() → Any | None

Executes the given command for async callbacks

Returns:

  • The return value from the callback if the command executed successfully,

  • or the return value from the error callback if an exception occurred and an error callback is set.

Raises:

Exception – Any exception raised during execution if error callback is not set.

async cmdtools.base.execute(command: Cmd, callback: Callback, *, attrs: Attributes | Dict[str, Any] | None = None)

A simple executor using Executor

Parameters:

  • command (Cmd) – The command object to be executed.

  • callback (Callback) – A function that will be invoked when the command is executed.

  • attrs (AttributeType) – Additional attributes to be passed to the callback context.

Returns:

  • The return value from the callback if the command executed successfully,

  • or the return value from the error callback if an exception occurred and an error callback is set.

Raises:

  • Exception – Any exception raised during execution if no error callback is assigned.

  • TypeError –

    • If callback is not a Callback. - If callback types do not match.

cmdtools.errors

exception cmdtools.errors.CmdBaseException(message: str, *args)

Bases: Exception

exception cmdtools.errors.ConversionError(message: str, option: str)

Bases: CmdBaseException

Raises when failed to convert an object to a specific type

Parameters:

  • message (str) – Error message.

  • option (str) – Name of the option.

exception cmdtools.errors.NotEnoughArgumentError(message: str, option: str)

Bases: CmdBaseException

Raises when an option is missing an argument.

Parameters:

  • message (str) – Error message.

  • option (str) – Name of the option.

exception cmdtools.errors.NotFoundError(message: str, name: str | None = None)

Bases: CmdBaseException

Raises when a command or a command module is not found

Parameters:

  • message (str) – Error message.

  • name (str) – Name of the identifier.