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 function

Each 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