API Reference

class command4bot.CommandsManager(context_reg: Optional[command4bot.context.ContextRegistry] = None, command_reg: Optional[command4bot.command.BaseCommandRegistry] = None, fallback_reg: Optional[command4bot.fallback.FallbackRegistry] = None, config: Optional[command4bot.manager.Config] = None, **kwargs)

close(name: str) → None

Mark a command or group as closed.

Parameters

name (str) – The name of the command or group to close.

command(command_func: command4bot.typing_ext.F) → command4bot.typing_ext.F

command(command_func: None = None, *, keywords: Iterable[str] = None, groups: Iterable[str] = None) → Callable[[command4bot.typing_ext.F], command4bot.typing_ext.F]

Decorator to register a command handler.

The command handler is called with the rest of the input (that is, without keyword it self), and optional keywords passed to CommandsManager.exec, when input matches its keywords.

The first non-empty line of the function’s docstring will be used as brief help string of the command. And the whole docstring will be used as full help string.

Parameters

• keywords (Iterable[str], optional) – Keywords for command. A keyword is a leading word of text input, separated with the rest part by a space. Defaults to the name of the comamnd function

• groups (Iterable[str], optional) – Group names of the command, defaults to []

context(context_func: command4bot.typing_ext.F) → command4bot.typing_ext.F

context(context_func: None = None, *, enable_cache: bool = True) → Callable[[command4bot.typing_ext.F], command4bot.typing_ext.F]

Decorator to register a context (a.k.a. command dependency).

This decorator can be used with or without parentheses.

exec(content: str, **kwargs) → Any

Execute given text input content

Parameters

content (str) – content to execute

Returns

execution result

Return type

Any

fallback(fallback_func: command4bot.typing_ext.F) → command4bot.typing_ext.F

fallback(fallback_func: None = None, *, priority: int = 10) → Callable[[command4bot.typing_ext.F], command4bot.typing_ext.F]

Decorator to register a fallback handler.

The fallback handlers registered are called in order of priority, with the original text input (content) and all other keyword parameters passed to CommandsManager.exec, until the handler returns something other than None, when there is no command found to handle the input.

Parameters

priority (int, optional) – Fallback handlers with higher priority will be called first, defaults to 10

get_possible_keywords_help(keyword: str) → List[str]

Get the help of keywords similar to keyword.

Used by help_with_similar.

Parameters

keyword (str) – The misspelled keyword to find similar keywrod for.

Returns

Brief help string of the similar commands.

Return type

List[str]

help_with_similar(content: str, **kwargs) → str

Return helps with similar commands hint.

This is the default fallback handler and will be registered in __init__.

Parameters

content (str) – The text input

Returns

Help message

Return type

str

open(name: str) → None

Mark a command or group as open.

Parameters

name (str) – The name of the command or group to open.

class command4bot.Command(command_func: Callable, keywords: Iterable[str], groups: Iterable[str], parameter_ignore: Iterable[str], context_ignore: Iterable[str], payload_parameter: str)

Create a Command

Parameters

• command_func (Callable) – Command handler

• keywords (Iterable[str]) – Keywords for the command

• groups (Iterable[str]) – Groups the command belongs to

• parameter_ignore (Iterable[str]) –

  Ignore these parameters of command handlers when constructing keyword arguments to pass.

  See also Config.command_parameter_ignore

• context_ignore (Iterable[str]) –

  Do not regard these parameters of command handlers as context names.

  See also Config.command_context_ignore

• payload_parameter (str) – [description]

class command4bot.CommandRegistry

class command4bot.Context(context_func: command4bot.typing_ext.F, enable_cache: bool = True)

class command4bot.ContextRegistry

check_command(command: command4bot.command.Command) → None

Check whether command has unregistered context

Parameters

command (Command) – command to check

Raises

ValueError – Unrecognized context name: “{context_name}”

get(context_name: str) → command4bot.context.Context

Get context by name from registry

Parameters

context_name (str) – Name of the context

Returns

context

Return type

Context

register(context: command4bot.context.Context) → None

Add context into registry

Parameters

context (Context) – The context to add

Raises

ValueError – If context name duplicate

update_reference(command: command4bot.command.Command, increase: bool = True)

Update references of contexts from a command

Parameters

• command (Command) – The command of which contexts to update

• increase (bool, optional) – Increase reference or decrease, defaults to True

Raises

ValueError – When :attr:reference_count reaches negtive

class command4bot.FallbackRegistry