Library API

class wingcommander.WingCommander(name='', parent=None, *args, **kwargs)

Master class for command line applications.

Use as the base class for the definition of a command line application.

Parameters:

• name – name of the application
• parent – (optional) parent <WingCommander> object

Usage:

from wingcommander import WingCommander

class ShellApp(WingCommander):
    pass

app = ShellApp(name='example')

classmethod command(cmd=None, completions=None)

decorator method to convert a function and properties into a command for the new command line application.

returns a Command object.

Parameters:

• completions – (optional) A completion definition (see: Completions)
• cmd – function to be converted into a command in the application (it is the one being decorated)

Usage:

@ShellApp.command
def count(app):
    app.count = (app.count or 0) + 1
    return app.count

@ShellApp.command(completions=["start", "stop"])
def app(app, action="start"):
    if action == "start":
        app.state = "started"
    elif action == "stop":
        app.state = "stopped"
    return True

class wingcommander.Command(command)

Wrapper class for commands/actions used in a WingCommander

Base wrapper for the commands used in the WingCommander controller. It is meant to provide an accessible and extensible API around the functionality added via the CLI behavior of the controller.

Can be created manually and imported:

def echo_func(cmd, *args):
    return " ".join(args)

echo = Command(echo_func)
echo.update_help("echoes whatever you give it")
ShellApp.command(cmd=echo)

update_completion(completions)

Updates the completion set for the Command in the command line interface. This takes any of the Completions accepted types and generates a new tab completion function. This can be a list of any possible arguments that can be completed at any position, a dict of arguments based on inherited position, or a function that will be used as the entire completion function.

Parameters:completions – completion set as described above and in the Completions section.

update_help(txt)

Updates the help text associated with the Command in the master application.

Parameters:txt – string containing the new help text to be displayed by the help command for this command.

Utility Functions

WingCommmander comes with a variety of functions to provide easy implementation of behaviors common to the everyday unix command line.

wingcommander.util.watch(func, wait=1)

Behaves like the watch command from unix command line. Will refresh the terminal stdout area at a specific interval with the output from a defined function. This can be used to regularly show output from an external source and provide a realtime updating text area that will resize with the data to display. Can be stopped with user input from stdin.

Parameters:

• func – function that is to be generating the output to be displayed. The output is whatever the function returns on each execution.
• wait – amount of time to sleep between executions of the function in order to update the display

Usage:

from wingcommander.util import watch

def print_file():
    contents = None
    with open('data', 'r') as f:
        contents = f.readlines()
        f.close()
    return contents

watch(print_file, 0.5)

wingcommander.util.tablize(data, max_length=-1, keys=None, dividers=['|', '', ''], labels=None, alignment=None)

Converts a tabular set of data into an aligned table for easier display in the terminal.

There are a number of options for customizing the output. The keys parameter will limit the keys to pull from each dict of data in the dataset. The labels parameter enables the header row and fills in the labels for each column.

The dividers parameter is used to configure the characters used to divide the various data cells. It is a list of length 3 that is defined:

0. The character used to divide between columns
1. The character used to divide between rows
2. The character used when the division between columns and rows occurs

The default is to display a pipe between columns and nothing between rows. A more ornamental set of dividers using box drawing characters, it can be found by importing BOX_DIVIDERS from wingcommander.util.tablize.

The alignment parameter is used to determine the alignment of the text in each column. The list should mirror the number of columns available and should probably be used with the keys parameter. The possible values are l, c, and r which correspond to left, center, and right aligned text respectively. You can also use the values LEFT, CENTER, and RIGHT from the wingcommander.util.tablize module.

Parameters:

• data – a list of dict sets of data to be displayed
• max_length – a limit on the maximum wdith of a column/length of a data point, a value of -1 means there is no limit
• keys – a list of keys to be used from the dict of data provided, if this is set to None all of the keys will be used
• dividers – a list defining the dividers to use when displaying the tabular data.
• labels – a list of the labels to be displayed above the table, if None no labels will be displayed
• alignment – a list of the alignment setup associated with each column

Usage:

>>> from wingcommander.util import tablize
>>> from wingcommander.util.tablize import BOX_DIVIDERS, LEFT, RIGHT
>>> tablize([{"name": "Joe", "occupation": "Teacher", "age": 45},
...   {"name": "Jane", "occupation": "Engineer", "age": 27},
...   {"name": "Mark", "occupation": "Astronomer", "age": 33}],
...  keys=["name", "occupation", "age"], max_length=7,
...  dividers=BOX_DIVIDERS, labels=["Name", "Job", "Age"],
...  alignment=[LEFT, LEFT, RIGHT])
...
Name │ Job     │ Age
─────┼─────────┼─────
Joe  │ Teacher │  45
─────┼─────────┼─────
Jane │ Enginee │  27
─────┼─────────┼─────
Mark │ Astrono │  33

wingcommander.util.alias(full, *short)

Adds an alias definition to a smartparsed command defition.

(see smartparse)

Parameters:

• full – keyword argument to be aliased
• short – all other parameters are the aliases that will be translated into the full keyword.

wingcommander.util.smartparse(func)

Converts the arguments going into the wrapped function to be intelligently parsed.

The function will have its arguments parsed and translated based on the rules defined in the decorators of the function using the alias decorator to allow for flags to be passed in and converted into keyword arguments.

So with a definition like:

from wingcommander.utils import smartparse, alias

@ShellApp.command
@smartparse
@alias("debug", "d", "dbg")
def run_stuff(_, debug=False, what="test"):
    return [name] if not debug else ["debug: {}".format(name)]

Would produce:

$ run_stuff
test
$ run_stuff --name notest
notest
$ run_stuff --debug
debug: test
$ run_stuff -d --name debugtest
debug: debugtest