Command line UI

BuddySuite Module Section

The argparse library is used to process flags passed into the BuddySuite modules, and the ArgumentParser.parse_args() variable is called 'in_args'. All command line logic is enclosed in the command_line_ui() function of every buddy module. Once you have added the relevant content to the flags dictionary in workshop/buddy_resources.py, you can test for calls to your function as follows:

if in_args.your_flag_name:
    ...

Code in the command line UI section is responsible for doing sanity checks on user input, (almost always) calling one or more API functions, then writing information to stdout/stderr and/or printing the modified buddy object. The two helper functions _stdout() and _stderr() should be used to send almost everything to the terminal window, and _stdout() MUST NOT be used if the buddy_object is also printed. This is because the BuddySuite is built to accept piped data and anything sent to stdout will be treated as input; if extra stuff is printed before or after the buddy object, the next buddy module called will undoubtably fail to parse stdin. Also resist the urge to use sys.stderr() directly. Anything printed with _stderr() can be suppressed with the -q flag if the user wants to ignore your carefully thought out warnings and errors.

To output the buddy object, use the following functions from each respective module:

Module	Print function
SeqBuddy	_print_recs(sb_obj)
AlignBuddy	_print_alignments(alb_obj)
PhyloBuddy	_print_trees(pb_obj)
DatabaseBuddy	_print_recs(db_obj) for sequences; str(db_obj) for summary

A key consideration for your code in the command line section is to catch all conceivable exceptions, then deal with them gracefully. The program should never crash from the command line, so is no place for the 'raise' clause! This constraint is in place because all crashes are recorded and sent to the core developers if users are participating in the software improvement program (we don't want to be spammed with raised exceptions resulting from user typos). Try to glean the users meaning if it can be done with minimal ambiguity, print informative warning messages where appropriate (using _stderr()), and if the user insists on providing non-sensical arguments then it's time to stop the program with the _raise_error() helper function.

At the end of your command line code, block further execution with the _exit() helper function. This does some house keeping before ending the program.

Example

# Insert Seq
if in_args.insert_seq:
    location = in_args.insert_seq[1]
    if location not in ['start', 'end']:
        try:
            location = int(location)
        except ValueError("Location must be start, end, or integer index") as e:
            _raise_error(e, "insert_seq")
    _print_recs(insert_sequence(seqbuddy, in_args.insert_seq[0], location))
    _exit("insert_seq")