Command
Commands are associated to consoles through the level
attribute and are evaluated in the REPL of a console using their run(...)
method. Completion and validation can be tuned using appropriate methods like explained hereafter.
Note that they are two possible formats : COMMAND VALUE
or COMMAND KEY VALUE
.
Styling¶
It is possible to define the style of commands, that is, how the class name is rendered when called in a console. Currently, four styles are supported :
Name | Command class name | Rendered command name |
---|---|---|
Lowercase | MyCommand |
mycommand |
Powershell | MyCommand |
My-Command |
Slugified (default) | MyCommand |
my-command |
Uppercase | MyCommand |
MYCOMMAND |
Command styling can be set using the set_style(...)
class method.
Example: Setting commands style
1 2 3 |
|
Definition¶
A command always subclasses the Command
generic entity class and can be dissected as follows :
- Docstring : This will be used for command's description in help messages (callable through the
help()
method). Note that this docstring is parsed like for any entity (as it is a feature of theEntity
class), meaning that metadata fields will be parsed and stored in a_metadata
class attribute. - Class attributes : They tune the applicability and nature of the command.
- Instance methods : They define the logic of the command, i.e.
run()
.
Here is the list of tunable class attributes :
Attribute | Type | Default | Description |
---|---|---|---|
aliases |
list (str ) |
[] |
the list of aliases for the command |
alias_only |
bool |
False |
whether only the aliases defined in the related list should be considered or also the converted command class name |
applies_to |
list (str ) |
[] |
a list of modules this command applies to |
except_levels |
list (str ) |
[] |
a list of non-applicable levels |
keys |
list (str ) or dict |
[] |
a list of possible keys or a dictionary of keys and associated values (this implies the second format with key-value) |
level |
str |
"general " |
command's level ; "general " means that it applies to all console levels |
single_arg |
bool |
False |
handle everything after the command as a single argument |
values |
list (str ) |
Example: Making a command in Powershell style with an alias and applicable to the module level
1 2 3 4 5 6 7 8 9 |
|
Completion¶
Completion is defined according to the command format and the related method signature is adapted accordingly. So, if a command is value-only, it can own a complete_values()
method with no argument. If a command has both a key and a value, it can own a complete_keys()
method taking no argument and a complete_values(key)
method that can be tuned according to the key entered in the incomplete command.
By default, the Command
class has both complete_keys
and complete_values
methods implemented, relying on the signature of the run(...)
method to determine command's format. Completion is handled according to the format :
COMMAND VALUE
: Then onlycomplete_values
is used, handling thevalues
class attribute as a list.-
COMMAND KEY VALUE
: This one usescomplete_keys
, handling thekeys
class attribute as a list in priority, otherwise thevalues
class attribute as a dictionary whose keys are the equivalent to thekeys
class attributecomplete_values
, handling thevalues
class attribute as a dictionary whose values for the key given in argument (if not given, all the values aggregated from all the keys) give the completion list
Example: Default completion for key-values (second command format)
1 2 3 4 5 6 7 |
|
This command will yield a completion list of :
-
["key1", "key2", "key3"]
when entering "do-something
" (or "do-something
" and a part of the possible key, without a trailing whitespace) and pressing the tab key twice -
["4", "5", "6"]
when entering "do-something key2
" and pressing the tab key twice
Validation¶
Validation can be especially useful as, within the CLI application, an error is dynamically displayed while typing a command, relying on command's validate()
method. Like the completion methods, this is defined according to the signature of the run(...)
method.
By default, the Command
class has a validate
method that relies on both complete_keys
and complete_values
methods to check inputs against valid keys and values.
Example: Key-value validation
According to the previous example, a validation error is raised as the given value is not part of the possible values for the given key :