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 thanNone
, 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
- 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¶