webdriver_test_tools.common.cmd.cmd module

Functions for common command line formatting and procedures.

webdriver_test_tools.common.cmd.cmd.PROMPT_PREFIX = '> '

Constant for string prepended to input prompts

webdriver_test_tools.common.cmd.cmd.INDENT = ' '

Constant for string used for terminal indentation

webdriver_test_tools.common.cmd.cmd.COLORS = {None: <class 'str'>, 'error': '\x1b[1m\x1b[31m', 'warning': '\x1b[33m', 'success': '\x1b[32m', 'info': '\x1b[36m', 'prompt': '\x1b[35m', 'title': '\x1b[34m', 'emphasize': '\x1b[1m'}

Color/formatting functions for different types of output

webdriver_test_tools.common.cmd.cmd.print_exception(e)

Format and print the string representation of an exception

Parameters

e – The exception to print

webdriver_test_tools.common.cmd.cmd.print_warning(text)

Format and print a warning message

Parameters

text – Warning message to print

webdriver_test_tools.common.cmd.cmd.print_info(text)

Format and print info message

Parameters

text – Info message to print

webdriver_test_tools.common.cmd.cmd.print_shortened(text, placeholder='...', indent='', fmt=None)

Print a string, shorten if it’s longer than the current terminal width

Essentially a wrapper around textwrap.shorten() (and optionally textwrap.indent()) that truncates based on the terminal width

If the printed string should be formatted, it is recommended to set the fmt parameter instead of passing in a formatted string. If a formatted string is truncated, then the colors aren’t reset, causing subsequent terminal output to be formatted as well

Parameters

• text – Text to print

• placeholder – (Default = ‘…’) Placeholder to use when truncating the string

• indent – (Optional) If set, indent using this string

• fmt – (Optional) A key in COLORS to use for formatting when printing the text

exception webdriver_test_tools.common.cmd.cmd.ValidationError

Bases: Exception

Exception raised if input validation fails

webdriver_test_tools.common.cmd.cmd.print_validation_change(message_format, original, changed)

Inform the user of changes to their input during validation. Used to keep output format consistent

Parameters

• message_format –

  A format string with 2 positional fields, one for the original value and one for the altered value. These fields should be surrounded with double quotes for better readability.

  example:

  ’”{0}” changed to “{1}” for compatibility’

• original – The original user input

• changed – The input after being altered

webdriver_test_tools.common.cmd.cmd.validate_nonempty(text)

Input validation function. Raises ValidationError if text is empty

Parameters

text – Text to validate

Returns

Validated text

webdriver_test_tools.common.cmd.cmd.validate_choice(choices, shorthand_choices={}, error_msg=None)

Returns a validation function for input with specific choice options

Parameters

• choices – A list of lowercase strings the user can choose from

• shorthand_choices –

  (Optional) A dictionary mapping short hand answers to options in choices. If user answers prompt with one of the keys in shorthand_choices, the validation function will treat their answer as shorthand_choices[answer].

  The following example values would allow ‘y’ and ‘n’ to be accepted as ‘yes’ and ‘no’, respectively:

  choices = ['yes', 'no']
  shorthand_choices = {
      'y': 'yes',
      'n': 'no',
  }
  validate_yes_no = validate_choice(choices, shorthand_choices)
  # Both of the following return 'yes'
  result0 = validate_yes_no('yes')
  result1 = validate_yes_no('y')
  

• error_msg –

  (Optional) Custom validation error message. By default, validation errors will have the message:

  'Please select a valid choice: [<choices>]'

  where <choices> is a comma separated representation of the values in choices.

Returns

A validation function that accepts a string and returns the corresponding item from choices if the string is valid

webdriver_test_tools.common.cmd.cmd.validate_yn(answer)

Validate y/n prompts

Parameters

answer – User response to y/n prompt. If a boolean value is passed (e.g. if a prompt received parsed_input=True), it is treated as a y/n answer and considered valid input

Returns

True if user answered yes, False if user answered no

webdriver_test_tools.common.cmd.cmd.validate_package_name(package_name)

Removes and replaces characters to ensure a string is a valid python package name

Parameters

package_name – The desired package name

Returns

Modified package_name with whitespaces and hyphens replaced with underscores and all invalid characters removed

webdriver_test_tools.common.cmd.cmd.validate_module_name(module_name)

Removes and replaces characters to ensure a string is a valid python module file name

Parameters

module_name – The desired module name. If the name ends in .py, the extension will be removed

Returns

Modified module_name with whitespaces and hyphens replaced with underscores and all invalid characters removed

webdriver_test_tools.common.cmd.cmd.validate_module_filename(module_filename, suppress_ext_change=True)

Removes and replaces characters to ensure a string is a valid python module file name

Essentially a wrapper around validate_module_name() that makes sure a .py extension is added to the end if needed

Parameters

• module_filename – The desired module file name. If the .py extension is excluded, it will be appended after validation

• suppress_ext_change – (Default: True) If False, print message when appending .py extension to file name. Suppressed by default, as the user shouldn’t typically be required to append .py themselves

Returns

Modified module_filename with whitespaces and hyphens replaced with underscores, all invalid characters removed, and a ‘.py’ extension appended (if necessary)

webdriver_test_tools.common.cmd.cmd.validate_class_name(class_name)

Removes and replaces characters to ensure a string is a valid python class name

Parameters

class_name – The desired class name

Returns

Modified class_name with invalid characters removed/replaced

webdriver_test_tools.common.cmd.cmd.prompt(text, *description, default=None, validate=<function validate_nonempty>, parsed_input=None, trailing_newline=True)

Prompt the user for input and validate it

Parameters

• text – Text to display in prompt

• description – (Optional) Positional arguments after text will be printed once before user is prompted for input. Each argument will be printed on a new line

• default – (Optional) default value

• validate – (Default = validate_nonempty) Validation function for input

• parsed_input – (Default = None) If parsed_input is set to something other than None, parser will attempt to validate it. If validation is successful, the input prompt will be skipped and the validated value of parsed_input will be returned. This allows for input to be passed through command line arguments, but still prompt the user in the event that it can’t be validated

• trailing_newline – (Default = True) Print a blank line after receiving user input and successfully validating

Returns

Validated input