Introduction to straight.command

straight.command is a framework for easily describing commands and their options, and allowing them to be extended with additional options and even sub-commands through easy-to-maintain plugins, via the straight.plugin plugin loader. Command-line options can be defined in a declarative syntax, which should be very familiar to many developers.

This is a very early stage in development.

Example

#!/usr/bin/env python

from __future__ import print_function
import sys
from straight.command import Command, Option, SubCommand

class List(Command):
    def run_default(self, **extra):
        for line in open(self.parent.args['filename']):
            print(line.strip('\n'))

class Add(Command):
    new_todo = Option(dest='new_todo', action='append')

    def run_default(self, new_todo, **extra):
        with open(self.parent.args['filename'], 'a') as f:
            for one_todo in new_todo:
                print(one_todo.strip('\n'), file=f)

class Todo(Command):
    filename = Option(dest='filename', action='store')

    list = SubCommand('list', List)
    add = SubCommand('add', Add)

if __name__ == '__main__':
    Todo().run(sys.argv[1:])

This example shows several commands with declaratively defined options, including two of them being declared as subcommands of the third.

We can see a number of the features of straight.command in this example.

Command options are declared with instances of Option assigned in the Command subclass, much like the declarative nature of many ORM tools declaring table columns, so this should be familiar to many developers.

The Command Processing Phases

The command structure and the processing of commands is defined carefully in a series of phases of parsing, preparing, and executing. Running the command passes through each of these phases to collect the parameters, process them, and execute the command.

  • Parse The command line parameters are parsed into their components.
  • Prepare The command is prepared according to the parameters provided.
  • Execute The command is finally executed.

Parse

The command line arguments are broken into a list of strings, and passed into the process. The Command will parse these option strings by passing all of them to each Option it has, giving each option a chance to consume one or more of the parameters, if it can. Once all of the parameters have been consumed, or none of the options are able to consume any of the remaining parameters, the parsing is complete.

Prepare

Then an option is able to consume one or more of the parameter strings for the command, it prepares the command in some way. It may store a value provided by the option, set a flag, or even enable some specific task the command should perform, such as reporting help text about itself.

The options prepare by invoking an action.

Execute

After all the parameters are consumed by the options, the command itself will execute. This is done by calling the execute() method on the command, which is passed all the collected parameter values as keyword arguments.

Indices and tables