Input/Output

Prompt Class APIs

class okaara.prompt.Prompt(input=<open file '<stdin>', mode 'r' at 0x7fcaea6710c0>, output=<open file '<stdout>', mode 'w' at 0x7fcaea671150>, normal_color='x1b[0m', enable_color=True, wrap_width=None, record_tags=False)

Used to communicate between the application and the user. The Prompt class can be subclassed to provide custom implementations of read and write to alter the input/output sources. By default, stdin and stdout will be used.

__init__(input=<open file '<stdin>', mode 'r' at 0x7fcaea6710c0>, output=<open file '<stdout>', mode 'w' at 0x7fcaea671150>, normal_color='x1b[0m', enable_color=True, wrap_width=None, record_tags=False)

Creates a new instance that will read and write to the given streams.

Parameters:

• input (file) – stream to read from; defaults to stdin
• output (file) – stream to write prompt statements to; defaults to stdout
• normal_color (str (one of the COLOR_* variables in this module)) – color of the text to write; this will be used in the color function to reset the text after coloring it
• enable_color (bool) – determines if this prompt instance will output any modified colors; if this is false the color() method will always render the text as the normal_color
• wrap_width (int or None) – if specified, content written by this prompt will automatically be wrapped to this width
• record_tags (bool) – if true, the prompt will keep track of tags passed to all write calls

center(text, width=None)

Centers the given text. Nothing is output to the screen; the formatted string is returned. The width in which to center is the first non-None value in the following order:

• Provided width parameter
• Instance-level wrap_width value
• Terminal width

Parameters:

• text (str) – text to center
• width (int) – width to center the text between

Returns:

string with spaces padding the left to center it

Return type:

str

clear(clear_character='x1b[2J')

Writes one of the clear characters to the screen. If none is given, the entire screen is cleared. One of the CLEAR_* variables can be used to scope the cleared space.

Parameters:clear_character (str) – character code to write; should be one of the CLEAR_* variables

color(text, color)

Colors the given text with the given color, resetting the output back to whatever color is defined in this instance’s normal_color. Nothing is output to the screen; the formatted string is returned.

Parameters:

• text (str) – text to color
• color (str) – coding for the color (see the COLOR_* variables in this module)

Returns:

new string with the proper color escape sequences in place

Return type:

str

get_read_tags()

Returns the values for all tags that were passed to read calls. If record_tags is enabled on this instance and a tag was not specified, an empty string will be added in its place.

Returns:list of tag values; empty list if record_tags was set to false Return type:list

get_tags()

Returns all tags for both read and write calls. Unlike read_tags and write_tags, the return value is a list of tuples. The first entry in the tuple will be one of [TAG_READ, TAG_WRITE] to indicate what triggered the tag. The second value in the tuple is the tag itself.

Returns:list of tag tuples: (tag_type, tag_value); empty list if record_tags was set to false Return type:list

get_write_tags()

Returns the values for all tags that were passed to write calls. If record_tags is enabled on this instance and a tag was not specified, an empty string will be added in its place.

Returns:list of tag values; empty list if record_tags was set to false Return type:list

move(direction)

Writes the given move cursor character to the screen without a new line character. Values for direction should be one of the MOVE_* variables.

Parameters:direction (str) – move character to write

prompt(question, allow_empty=False, interruptable=True)

Prompts the user for an answer to the given question, re-prompting if the answer is blank.

Parameters:

• question (str) – displayed to the user when prompting for input
• allow_empty (bool) – if True, a blank line will be accepted as input
• interruptable (bool) – if True, keyboard interrupts will be caught and None will be returned; if False, keyboard interrupts will raise as normal

Returns:

answer to the given question or the ABORT constant in this module if it was interrupted

prompt_default(question, default_value, interruptable=True)

Prompts the user for an answer to the given question. If the user does not enter a value, the default will be returned.

Parameters:default_value (string) – if the user does not enter a value, this value is returned

prompt_file(question, allow_directory=False, allow_empty=False, interruptable=True)

Prompts the user for the full path to a file, reprompting if the file does not exist. If allow_empty is specified, the validation will only be performed if the user enters a value.

prompt_menu(question, menu_values, interruptable=True)

Displays a list of items, allowing the user to select a single item in the list. The index of the selected item is returned. If interruptable is set to true and the user exits (through ctrl+c), the ABORT constant is returned.

Parameters:

• question (str) – displayed to the user prior to rendering the list
• menu_values (list of str) – list of items to display in the menu; the returned value will be one of the items in this list

Returns:

index of the selected item; ABORT if the user elected to abort

Return type:

int or ABORT

prompt_multiselect_menu(question, menu_values, interruptable=True)

Displays a list of items, allowing the user to select 1 or more items before continuing. The items selected by the user are returned.

Returns:list of indices of the items the user selected, empty list if none are selected; ABORT is returned if the user selects to abort the menu Return type:list or ABORT

prompt_multiselect_sectioned_menu(question, section_items, section_post_text=None, interruptable=True)

Displays a multiselect menu for the user where the items are broken up by section, however the numbering is consecutive to provide unique indices for the user to use for selection. Entries from one or more section may be toggled; the section headers are merely used for display purposes.

Each key in section_items is displayed as the section header. Each item in the list at that key will be rendered as belonging to that section.

The returned value will be a dict that maps each section header (i.e. key in section_items) and the value is a list of indices that were selected from the original list passed in section_items under that key. If no items were selected under a given section, an empty list is the value in the return for each section key.

For example, given the input data:

{ 'Section 1' : ['Item 1.1', 'Item 1.2'],
  'Section 2' : ['Item 2.1'],}

The following is rendered for the user:

Section 1
  -  1 : Item 1.1
  -  2 : Item 1.2
Section 2
  -  3 : Item 2.1

If the user entered 1, 2, and 3, thus toggling them as selected, the following would be returned:

{ 'Section 1' : [0, 1],
  'Section 2' : [0],}

However, if only 2 was toggled, the return would be:

{ 'Section 1' : [1],
  'Section 2' : [],}

If the user chooses the “abort” option, None is returned.

Parameters:

• question (str) – displayed to the user before displaying the menu
• section_items (dict {str : list[str]}) – data to be rendered; each key must be a string and each value must be a list of strings
• section_post_text (str) – if specified, this string will be displayed on its own line between each section

Returns:

selected indices for each list specified in each section; ABORT if the user elected to abort the selection

Return type:

dict {str : list[int]} or ABORT

prompt_number(question, allow_negatives=False, allow_zero=False, default_value=None, interruptable=True)

Prompts the user for a numerical input. If the given value does not represent a number, the user will be re-prompted until a valid number is provided.

Returns:number entered by the user that conforms to the parameters in this call Return type:int

prompt_password(question, verify_question=None, unmatch_msg=None, interruptable=True)

Prompts the user for a password. If a verify question is specified, the user will be prompted to match the previously entered password (suitable for things such as changing a password). If it is not specified, the first value entered will be returned.

The user entered text will not be echoed to the screen.

Returns:entered password Return type:str

prompt_range(question, high_number, low_number=1, interruptable=True)

Prompts the user to enter a number between the given range. If the input is invalid, the user wil be re-prompted until a valid number is provided.

prompt_values(question, values, interruptable=True)

Prompts the user for the answer to a question where only an enumerated set of values should be accepted.

Parameters:values (list) – list of acceptable answers to the question Returns:will be one of the entries in the values parameter Return type:string

prompt_y_n(question, interruptable=True)

Prompts the user for the answer to a yes/no question, assuming the value ‘y’ for yes and ‘n’ for no. If neither is entered, the user will be re-prompted until one of the two is indicated.

Returns:True if ‘y’ was specified, False otherwise Return type:boolean

read(prompt, tag=None, interruptable=True)

Reads user input. This will likely not be called in favor of one of the prompt_* methods.

Parameters:prompt (string) – the prompt displayed to the user when the input is requested Returns:the input specified by the user Return type:string

reset_position()

Moves the cursor back to the location of the cursor at the last point save_position was called.

save_position()

Saves the current location of the cursor. The cursor can be moved back to this position by using the reset_position call.

classmethod terminal_size()

Returns the width and height of the terminal.

Returns:tuple of width and height values Return type:(int, int)

wrap(content, wrap_width=None, remaining_line_indent=0)

If the wrap_width is specified, this call will introduce new line characters to maintain that width.

Parameters:

• content (str) – text to wrap
• wrap_width (int) – number of characters to wrap to
• remaining_line_indent (int) – number of characters to indent any new lines generated from this call

Returns:

wrapped version of the content string

Return type:

str

write(content, new_line=True, center=False, color=None, tag=None, skip_wrap=False)

Writes content to the prompt’s output stream.

Parameters:

• content (string) – content to display to the user
• skip_wrap (bool) – if true, auto-wrapping won’t be applied; defaults to false

Recorder Class APIs

class okaara.prompt.Recorder

Suitable for passing to the Prompt constructor as the output, an instance of this class will store every line written to it in an internal list.

Script Class APIs

class okaara.prompt.Script(lines)

Suitable for passing to the Prompt constructor as the input, an instance of this class will return each line set within on each call to read.