Command line helpers: getting stats, GUIS, a shell and more automagically !

Requires the python argparse library.

Ecto has a few helper functions for commandline parsing using the argparse library. These are useful for having scripts that may run with multiple ecto schedulers based on command line args.

sample

A sample of using argparse with ecto.

#!/usr/bin/env python
# 
# Copyright (c) 2011, Willow Garage, Inc.
# All rights reserved.
# 
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#     * Redistributions of source code must retain the above copyright
#       notice, this list of conditions and the following disclaimer.
#     * Redistributions in binary form must reproduce the above copyright
#       notice, this list of conditions and the following disclaimer in the
#       documentation and/or other materials provided with the distribution.
#     * Neither the name of the Willow Garage, Inc. nor the names of its
#       contributors may be used to endorse or promote products derived from
#       this software without specific prior written permission.
# 
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
# 
import ecto
from ecto.opts import scheduler_options, run_plasm
from ecto import Constant
from ecto.ecto_test import Multiply, Printer
import argparse

parser = argparse.ArgumentParser(description='My awesome program thing.')

#our local command line args.
parser.add_argument('--value', metavar='VALUE', dest='value',
                    type=float, default=3, help='A value to use a constant.')
parser.add_argument('--factor', metavar='FACTOR', dest='factor',
                    type=float, default=5, help='The factor to multiply the constant with.')

#add ecto scheduler args.
scheduler_options(parser)
options = parser.parse_args()

c = Constant(value=options.value)
m = Multiply(factor=options.factor)
pr = Printer()
plasm = ecto.Plasm()
plasm.connect(c[:] >> m[:],
              m[:] >> pr[:]
              )
#run the scheduler given the options, plasm, and our local variables.
run_plasm(options, plasm, locals=vars())

Running with --help gives us:

No module named PySide.QtCore
usage: sample_opts.py [-h] [--value VALUE] [--factor FACTOR]
                      [--niter ITERATIONS] [--shell] [--gui]
                      [--logfile LOGFILE] [--graphviz] [--dotfile DOTFILE]
                      [--stats]

My awesome program thing.

optional arguments:
  -h, --help          show this help message and exit
  --value VALUE       A value to use a constant.
  --factor FACTOR     The factor to multiply the constant with.

Ecto runtime parameters:
  --niter ITERATIONS  Run the graph for niter iterations. 0 means run until
                      stopped by a cell or external forces. (default: 0)
  --shell             'Bring up an ipython prompt, and execute
                      asynchronously.(default: False)
  --gui               Bring up a gui to help execute the plasm.
  --logfile LOGFILE   Log to the given file, use tail -f LOGFILE to see the
                      live output. May be useful in combination with --shell
  --graphviz          Show the graphviz of the plasm. (default: False)
  --dotfile DOTFILE   Output a graph in dot format to the given file. If no
                      file is given, no output will be generated. (default: )
  --stats             Show the runtime statistics of the plasm.

ipython

To use with ipython, simply pass --shell to the sample. This will result in the plasm being executed asynchronously, and pop you out into an ipython shell.

%  ./sample_opts.py --shell --niter=3
***** 15 ***** 0x14e1a90
***** 15 ***** 0x14e1a90
***** 15 ***** 0x14e1a90


Input <1>c.outputs.out
 Out[1]: 3

Input <2>m.outputs.out
 Out[2]: 15.0

Input <3>c.outputs.out = 5

Input <4>sched.execute(niter=2)
***** 25 ***** 0x14e1a90
***** 25 ***** 0x14e1a90
 Out[4]: 0

Notice how the shell has access to the local variables declared in the script.

Exposing cells to the parser

You can also automatically expose any of the parameters in a Cell like object to the argparse parser.

#!/usr/bin/env python
from ecto import Constant
from ecto.ecto_test import Multiply
import argparse

from ecto.opts import cell_options

parser = argparse.ArgumentParser(description='My awesome program thing.')

#add our cells to the parser
multiply_factory = cell_options(parser, Multiply, prefix='mult')
const_factory = cell_options(parser, Constant(value=0.50505), prefix='const')

args = parser.parse_args()

#use the factories in conjunction with the parsed arguments, to create our cells.
c = const_factory(args)
m = multiply_factory(args)

# ... construct graph do whatever else...

The help looks like:

No module named PySide.QtCore
usage: sample_opts2.py [-h] [--mult_factor MULT_FACTOR]
                       [--const_value CONST_VALUE]

My awesome program thing.

optional arguments:
  -h, --help            show this help message and exit

mult options:
  --mult_factor MULT_FACTOR
                        A factor to multiply by. ~ (default: 3.14)

const options:
  --const_value CONST_VALUE
                        Value to output ~ (default: 0.50505)
ecto.opts.cell_options(parser, CellType, prefix=None)[source]

Creates an argument parser group for any cell. CellType may be either a __class__ type, or an instance object.

cell_options returns a cell factory. The cell factory can be used to produce an instance of a cell based on the arguments parsed.

helper functions

ecto.opts.use_ipython(options, sched, plasm, locals={})[source]

Launch a plasm using ipython, and a scheduler of choice.

Keyword arguments: options – are from scheduler_options sched – is an already initialized scheduler for plasm. plasm – The graph to execute locals – are a dictionary of locals to forward to the ipython shell, use locals()

The variables options, sched, plasm, and all locals passed in will be available in the ipython context.

ecto.opts.run_plasm(options, plasm, locals={})[source]

Run the plasm given the options from the command line parser. :param options: The command line, preparsed options object. It is assumed that you have filled this object using scheduler_options. :param plasm: The plasm to run. :param locals: Any local variables that you would like available to the iPython shell session.

ecto.opts.scheduler_options(parser, default_niter=0, default_shell=False, default_graphviz=False)[source]

Creates an argument parser for ecto schedulers. Operates inplace on the given parser object.

ecto.opts.doit(plasm, description='An ecto graph.', locals={}, args=None, default_niter=0, default_shell=False, default_graphviz=False)[source]

doit is a short hand for samples, that is a combination of a call to scheduler_options, and then run_plasm. This function in not intended to allow customization of parameter parsing. If this is needed please call scheduler_options and run_plasm yourself.

Parameters:
  • args – If this is None, default to using the sys.argv args, otherwise this overrides it.
  • locals – May be used to forward any local variables to the ipython shell. Suggest either vars() or locals() to do this.
  • default_shell – Override
  • default_graphviz – Override