Commands¶
The GetInputCommand
class is used to define commands that can be run while getting command line input in
cooked_input
.
GetInputCommand:¶
-
class
cooked_input.
GetInputCommand
(cmd_action, cmd_dict=None)¶ GetInputCommand is used to create commands that can be used while getting input from
GetInput.get_input()
param Callable[str, str, Dict[str, Any], Tuple[str, Any]] cmd_action: callback function used to process the command param Dict[Any, Any] cmd_dict: (optional) a dictionary of data passed to the cmd_action
callback functionEach command has a callback function (
cmd_action
) and optional data (cmd_dict
).cmd_action
is a callback function used for the command. The callback is called as follows-
cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Parameters: - cmd_str (str) – the string used to call the command
- cmd_vars (str) – additional arguments for the command (i.e. the rest of string used for the command input)
- Any] cmd_dict (Dict[str,) – a dictionary of additional data for processing the command (often None)
Command callback functions return a a tuple containing (COMMAND_ACTION_TYPE, value), where the command action type is one of the following:
Action Result COMMAND_ACTION_USE_VALUE
use the second value of the tuple as the input COMMAND_ACTION_CANCEL
cancel the current input (raises GetInputInterrupt
exception)COMMAND_ACTION_NOP
do nothing - continues to ask for the input For convenience command action callbacks can return a
CommandResponse
namedtuple instance:CommandResponse(action, value)
The
cmd_dict
dictionary can be used to pass data useful in processing the command. For instance, a database session and the name of the user can be passed with:cmd_dict = {'session': db_session, 'user_name': user_name } lookup_user_cmd = GetInputCommand(lookup_user_action, cmd_dict)
The following show examples of of each type of command:
def use_color_action(cmd_str, cmd_vars, cmd_dict): print('Use "red" as the input value') return (COMMAND_ACTION_USE_VALUE, 'red') def cancel_action(cmd_str, cmd_vars, cmd_dict): return CommandResponse(COMMAND_ACTION_CANCEL, None) def show_help_action(cmd_str, cmd_vars, cmd_dict): print('Commands:') print('---------') print('/? - show this message') print('/cancel - cancel this operation') print('/red - use red as a value') print('/reverse - return the user's name reversed') return CommandResponse(COMMAND_ACTION_NOP, None) cmds = { '/?': GetInputCommand(show_help_action), '/cancel': GetInputCommand(cancel_action), '/red': GetInputCommand(use_color_action, {'color': 'red'}), '/reverse': GetInputCommand(user_color_action, {'user': 'fred'}) } try: result = get_string(prompt=prompt_str, commands=cmds) except GetInputInterrupt: print('Operation cancelled (received GetInputInterrupt)')
Note
Nothing stops you from using
cooked_input
to get additional input within a command action callback. For example, the cancel command could be extended to confirm the user wants to cancel the current input:def cancel_action(cmd_str, cmd_vars, cmd_dict): response = get_yes_no(prompt="Are you sure you want to cancel?", default='no') if response == 'yes': print('operation cancelled!') return CommandResponse(COMMAND_ACTION_CANCEL, None) else: return CommandResponse(COMMAND_ACTION_NOP, None)
-
Command Action Functions:¶
The following pre-defined action functions can be used for commands (see GetInputCommand
).
first_page_cmd_action¶
-
cooked_input.
first_page_cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Command action to show the first (home) page in a paginated table. This command raises a
FirstPageRequest
exception.Parameters: - cmd_str – ignored
- cmd_vars – ignored
- cmd_dict – ignored
Returns: None
last_page_cmd_action¶
-
cooked_input.
last_page_cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Command action to show the last (end) page in a paginated table. This command raises a
LastPageRequest
exception.Parameters: - cmd_str – ignored
- cmd_vars – ignored
- cmd_dict – ignored
Returns: None
prev_page_cmd_action¶
-
cooked_input.
prev_page_cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Command action to show the previous page in a paginated table. This command raises a
PageUpRequest
exception.Parameters: - cmd_str – ignored
- cmd_vars – ignored
- cmd_dict – ignored
Returns: None
next_page_cmd_action¶
-
cooked_input.
next_page_cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Command action to show the next page in a paginated table. This command raises a
PageDownRequest
exception.Parameters: - cmd_str – ignored
- cmd_vars – ignored
- cmd_dict – ignored
Returns: None
scroll_up_one_row_cmd_action¶
-
cooked_input.
scroll_up_one_row_cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Command action to scroll up one row in a paginated table. This command raises a
UpOneRowRequest
exception.Parameters: - cmd_str – ignored
- cmd_vars – ignored
- cmd_dict – ignored
Returns: None
scroll_down_one_row_cmd_action¶
-
cooked_input.
scroll_down_one_row_cmd_action
(cmd_str, cmd_vars, cmd_dict)¶ Command action to scroll down one row in a paginated table. This command raises a
DownOneRowRequest
exception.Parameters: - cmd_str – ignored
- cmd_vars – ignored
- cmd_dict – ignored
Returns: None