Skip to content

Instantly share code, notes, and snippets.

Last active October 25, 2019 10:35
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 4 You must be signed in to fork a gist
  • Save bewest/1202975 to your computer and use it in GitHub Desktop.
Save bewest/1202975 to your computer and use it in GitHub Desktop.
Using pyCLI to create some commands and subcommands.

Hello world python subcommand pattern

Using pyCLI vs commando to create some commands and subcommands.

git clone python-hello-subcommand

How to write a well behaved console application? The ones with the best UIs allow configuration of core commands in a flexible config file, can override important defaults from the environment, and use the subcommand pattern to logically organize commands.

It should be tab-completable, with nice help output.

Circa 2013, there's still not a good way to do this. Here are a few attempts.


In terms of frameworks, this one is the only one with the needed pre-setup hook needed to do an initial pass over the arguments to sniff any parameters which might be used to then initialize the rest of the arguments. This happens, for example, when determining which configuration file to use. If we know there is a configuration file, why not make the configured values default?

Goal is to get a combination of tab completion + subcommands in such a way that will allow me to implement independent python modules as a main command, and then re-use the implementation as a subcommand in my main app.


This attempt just uses argparse to iterate over a bunch of example subcommands. The behavior is pretty close to what we want; it's clear where to add reading from environment variables, and the set_parser method offers a nice way to set arguments, regardless of where the parser came form. argparse does not allow any way of re-using parser logic for subcommands.

At one point I tried separating the parsing into two phases, one for the core to find the subcommand, and then another to pass the remaining args to the subcommand as a main parser, but autocompletion failed to cope with this setup.

These examples on the other hand are tab completable subcommands with default configuration read from a config file.

$ ./simple
usage: simple [-h] [-d] [-c CONFIG] {qux,fux,bux,lux} ...

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug
  -c CONFIG, --config CONFIG

Title Group A:
  This is a long description on a simple command.

  {qux,fux,bux,lux}     some help on group A
$ ./simple 
bux       --config  --debug   -h        lux       
-c        -d        fux       --help    qux       
$ ./simple lux 
final pass Namespace(command='lux', config='example.conf', debug=False, foo='XXX', run=<bound method F.main of <__main__.F object at 0x2417d50>>) None
Hello, I'm lux.
 <__main__.F object at 0x2417d50>,
 Namespace(command='lux', config='example.conf', debug=False, foo='XXX', run=<bound method F.main of <__main__.F object at 0x2417d50>>)]
$ ./simple qux
final pass Namespace(command='qux', config='example.conf', debug=False, foo='baz', run=<bound method F.main of <__main__.F object at 0x1c632d0>>) None
Hello, I'm qux.
 <__main__.F object at 0x1c632d0>,
 Namespace(command='qux', config='example.conf', debug=False, foo='baz', run=<bound method F.main of <__main__.F object at 0x1c632d0>>)]
$ ./simple qux --help
usage: simple qux [-h] [--foo FOO]

long desc of qux

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

So the only thing missing is the default values from the help output.

import argparse
import ConfigParser
import os
""" -
def _identity(x):
return x
_SENTINEL = object()
class AddConfigFile(argparse.Action):
def __call__(self,parser,namespace,values,option_string=None):
#I can never remember if `values` is a list all the time or if it
#can be a scalar string ... -- This takes care of both.
if isinstance(values,basestring):
class ArgumentConfigEnvParser(argparse.ArgumentParser):
def __init__(self,*args,**kwargs):
Added 2 new keyword arguments to the ArgumentParser constructor:
config --> List of filenames to parse for config goodness
default_section --> name of the default section in the config file
self.config_files = kwargs.pop('config',[]) #Must be a list
self.default_section = kwargs.pop('default_section','MAIN')
self._action_defaults = {}
def add_argument(self,*args,**kwargs):
works like ArgumentParser.add_argument except that we've added an action:
config: add a config file to the parser
and we've added the ability to specify the section to pull the data from in the
config file via the `section` keyword. Relies on the undocumented fact that
`ArgumentParser.add_argument` actually returns the `Action` object that it creates.
We need this to reliably get `dest`, although we could probably write a simple
function to do this for us.
if 'action' in kwargs and kwargs['action'] == 'config':
kwargs['action'] = AddConfigFile
kwargs['default'] = argparse.SUPPRESS
#argparse won't know what to do with the section, so we'll pop it out and add it back in
#Also, we have to prevent any type conversion by argparse. We'll do it explicitly
#in parse_known_args. This way, we can reliably check whether argparse has replaced the default.
section = kwargs.pop('section',self.default_section)
type = kwargs.pop('type',_identity)
default = kwargs.pop('default',_SENTINEL)
kwargs.update(default=_SENTINEL if default is not argparse.SUPPRESS else argparse.SUPPRESS)
action = argparse.ArgumentParser.add_argument(self,*args,**kwargs)
self._action_defaults[action.dest] = (args,kwargs)
return action
def parse_known_args(self,args=None, namespace=None):
#parse_args calls parse_known_args, so we should be OK with this...
ns, argv = argparse.ArgumentParser.parse_known_args(self,args=args,namespace=namespace)
config_parser = ConfigParser.SafeConfigParser()
config_files = [os.path.expanduser(os.path.expandvars(x)) for x in self.config_files]
for dest,(args,init_dict) in self._action_defaults.items():
type_converter = init_dict['type']
default = init_dict['default']
obj = default
if getattr(ns,dest,_SENTINEL) is not _SENTINEL: #found on command line
obj = getattr(ns,dest)
else: #not found on commandline
try: #get from config file
obj = config_parser.get(init_dict['section'],dest)
except (ConfigParser.NoSectionError,ConfigParser.NoOptionError): #Nope, not in config file
try: #get from environment
obj = os.environ[dest.upper()]
except KeyError:
if obj is _SENTINEL:
elif obj is argparse.SUPPRESS:
return ns, argv
if __name__ == '__main__':
fake_config = """
with open('_config.file','w') as fout:
parser = ArgumentConfigEnvParser()
parser.add_argument('--config-file',action='config',help="location of config file")
parser.add_argument('--foo',type=str,action='store',default="grape",help="don't know what foo does ...")
parser.add_argument('--bar',type=int,default=7,action='store',help="This is an integer (I hope)")
parser.add_argument('--baz',type=float,action='store',help="This is an float(I hope)")
parser.add_argument('--qux',type=int,default='6',action='store',help="this is another int")
ns = parser.parse_args([])
parser_defaults = {'foo':"grape",'bar':7,'baz':None,'qux':6}
config_defaults = {'foo':'bar','bar':1}
env_defaults = {"baz":3.14159}
#This should be the defaults we gave the parser
print ns
assert ns.__dict__ == parser_defaults
#This should be the defaults we gave the parser + config defaults
d = parser_defaults.copy()
ns = parser.parse_args(['--config-file','_config.file'])
print ns
assert ns.__dict__ == d
os.environ['BAZ'] = "3.14159"
#This should be the parser defaults + config defaults + env_defaults
d = parser_defaults.copy()
ns = parser.parse_args(['--config-file','_config.file'])
print ns
assert ns.__dict__ == d
#This should be the parser defaults + config defaults + env_defaults + commandline
commandline = {'foo':'3','qux':4}
d = parser_defaults.copy()
ns = parser.parse_args(['--config-file','_config.file','--foo=3','--qux=4'])
print ns
assert ns.__dict__ == d
complete -F _optcomplete
# Copyright 2012-2013, Andrey Kislyuk and argcomplete contributors.
# Licensed under the Apache License. See for more info.
_python_argcomplete_global() {
if [[ "$1" == python* ]] || [[ "$1" == pypy* ]]; then
if [[ -f "${COMP_WORDS[1]}" ]] && (head -c 1024 "${COMP_WORDS[1]}" | grep --quiet "PYTHON_ARGCOMPLETE_OK") >/dev/null 2>&1; then
set -- "${COMP_WORDS[1]}"
elif (which "$1" && head -c 1024 $(which "$1") | grep --quiet "PYTHON_ARGCOMPLETE_OK") >/dev/null 2>&1; then
elif (which "$1" && head -c 1024 $(which "$1") | egrep --quiet "(EASY-INSTALL-SCRIPT|EASY-INSTALL-ENTRY-SCRIPT)" \
&& python-argcomplete-check-easy-install-script $(which "$1")) >/dev/null 2>&1; then
if [[ $ARGCOMPLETE == 1 ]] || [[ $ARGCOMPLETE == 2 ]]; then
local IFS=$(echo -e '\v')
"$1" 8>&1 9>&2 1>/dev/null 2>&1) )
if [[ $? != 0 ]]; then
complete -o nospace -o default -D -F _python_argcomplete_global
import sys
import commando
from pprint import pprint
import argcomplete # PYTHON_ARGCOMPLETE_OK
__version__ = '0.0.1-dev'
class ParamGroup(commando.param):
__params__ = ( ('-d', '--debug'), dict(action='store_true' ) )
def __init__(self):
params = self.params( )
args, kwds = params[0], params[1]
self.values = commando.application.values._make( (args, kwds) )
def params(self):
return self.__params__
## base_val = commando.values
class TaggedMemo(object):
# subcommand = base_val._make(((), dict()))
commando = True
params = [ ]
def __init__(self, name=None):
# default = base_val._make(((name, ), dict( )))
self.subcommand = getattr(self.main, 'subcommand', default)
self.params = [ ]
def __call__(self, app, params):
def main(self, params):
print "I'm an unsubclassed Command"
pprint([self, params])
class DemoRecurse(TaggedMemo):
@commando.subcommand('far', help='demo far recurse')
def main(self, params):
print "used decorator on a subclass"
class FooBar(commando.Application):
@commando.subcommand('one', help="one")
def one(self, params):
print "one"
@commando.subcommand('two', help="two")
def two(self, params):
print "two"
#@commando.command(description="my command description")
@commando.command('far', description='demo far recurse')
def main(self, params):
print "used decorator on a simple class"
class Root(commando.Application):
def print_usage(self):
self.__parser__.print_help( )
@commando.command(description="b - my command description")
@commando.param('-v', '--version', action='version',
version='%(prog)s ' + __version__)
@commando.param('-foo', dest='foo', action='store', type=str)
def main(self, app, params):
pprint([self, params])
@commando.subcommand('init', help="main command")
def init(self, params):
self.main(self, params)
@commando.subcommand('help', help="This help")
def help(self, params):
self.print_usage( )
@commando.subcommand('foo', help="foo command")
@commando.param('extra', action='store', type=str, nargs="*")
def foo(self, params):
pprint([self, params])
print "HAHA", params
f = FooBar( )
def __init__(self):
super(type(self), self).__init__( )
# print self.__parser__
print "foo.parser"
f = FooBar( )
print "foo.parser.subcommand"
# class Application(Root, commando.WeirdApp):
class Application(Root):
# __subcommands__ = [ FooBar( ), DemoRecurse('demo') ]
def __init__(self):
super(Application, self).__init__()
def main( ):
app = Root( ) )
#tree = commando.TreeApp(root=Root( ))
# )
if __name__ == '__main__':
main( )
from cli.log import LoggingApp
import argcomplete # PYTHON_ARGCOMPLETE_OK
from pprint import pprint
Very rough.
class Subcommand(object):
name = ''
def __init__(self, handler):
self.session = handler
def options(self):
return [ ]
def setup(self, parser):
self.parser = parser
for args, kwds in self.options( ):
parser.add_argument(*args, **kwds)
def help(self):
return self.__doc__
def main(self, app):
pprint([self, app])
class QuxApp(Subcommand):
"""Qux Does several special things"""
name = "qux"
class FuxApp(Subcommand):
"""Fux is accidently different."""
name = "fux"
class BuxApp(Subcommand):
"""Bux seems special, but it's a trick."""
name = "bux"
class BaxApp(Subcommand):
"""Bax seems special, bat it's a trick."""
name = "bax"
class FaxApp(Subcommand):
"""Fax is accidently different."""
name = "fax"
class QaxApp(Subcommand):
"""Qax Does several special things"""
name = "qax"
class Command(object):
"Fake help"
subcommands = { }
def __init__(self, name, subcommands=None):
self.subcommands = { } = name
if subcommands is not None:
for Flow in subcommands:
def __repr__(self):
return "%s:%s" % (, type(self))
def subcommand_factory(self, Flow):
return Flow(self)
def addFlow(self, Flow):
flow = self.subcommand_factory(Flow)
self.subcommands[] = flow
def base(self, params):
pprint(self, params)
print "Without a subcommand!!"
def setup(self, parser):
n =
self.parser = parser
pprint(['before', parser._positionals])
self.commands = parser.add_subparsers(dest='subcommand',
title="my commands title", ),
pprint(['after', parser._positionals])
#p = self.commands.add_parser(None, help='basic help')
for flow in self.subcommands.values( ):
#flow = Flow( )
p = self.commands.add_parser(,
def help(self):
return self.__doc__
def main(self, app):
subcommand = self.subcommands[app.params.subcommand]
def get_commands():
devices = [ ]
a = Command('AAA', [ FuxApp, BuxApp ] )
b = Command('BBB', [ FaxApp, QaxApp, ] )
c = Command('CCC', [ FuxApp, BaxApp, QuxApp, BuxApp ] )
return [ a, b, c ]
class GlobalOptions(object):
def setup(self):
print "setting up global options"
class Application(LoggingApp, GlobalOptions):
"""Test Hello World
name = "dispatcher"
commands = { }
def setup(self):
# just after wrapping argument during __call__
# !? or during __init__
super(Application, self).setup( )
self.add_param("bar", help="fake option", action='store_true')
self.subparsers = self.argparser.add_subparsers(dest='command', help='fake help on this command')
for dev in get_commands():
self.add_command( dev )
def pre_run(self):
# called just before main, updates params, parses args
super(Application, self).pre_run()
def add_command(self, command):
self.commands[] = command
parser = self.subparsers.add_parser(,
def main(self):
self.log.warn("hello world warn")
self.log.debug("hello world debug")"hello world info")
self.log.error("hello world error")
self.log.critical("hello world critical")
self.log.fatal("hello world fatal")
command = self.commands[self.params.command]
if __name__ == '__main__':
app = Application() )
Simple app using argparse.
How can I provide a bunch of subcommands, but make one of them a default?
from pprint import pprint, pformat
import argparse
import argcomplete # PYTHON_ARGCOMPLETE_OK
import logging
import ConfigParser
log = logging.getLogger(__name__)
class F(object):
def __init__(self, name): = name
self.parser = argparse.ArgumentParser(prog=name, description=self.descr( ), add_help=True)
def descr(self):
desc = "A very long description of %s" %
return desc
def set_parser(self, parser, options):
self.parser = parser
default=options.get('foo', 'XXX'))
def parse_args(self, argv):
return self.parser.parse_args(argv)
def main(self, app, params):
print "Hello, I'm %s." %
pprint([, 'params', self, params ])
class Simple(object):
This is a very simple description.
We'll simulate it very long here.
Very long indeed.
def global_parser(self):
desc = type(self).__doc__
parser = argparse.ArgumentParser(description=desc, add_help=False,
parser.add_argument('-d', '--debug', action='store_true')
parser.add_argument('-c', '--config', default="example.conf", type=str)
return parser
def __init__(self):
desc = type(self).__doc__
conf_parser = self.global_parser( )
self.pre_parser = argparse.ArgumentParser(add_help=False, parents=[conf_parser])
# first sniff for basic debuggery, help fill in defaults
self.known, args = self.pre_parser.parse_known_args( )
# then set up the real parser, cloning the initial one
self.parser = argparse.ArgumentParser(parents=[conf_parser], add_help=True,
self.commands = { }
if not args:
self.parser.print_help( )
def read_config(self, path):
self.config = config = getattr(self, 'config', ConfigParser.ConfigParser( ))
return config
def setup_a(self, parser, name='lalala'):
desc = """This is a long description on a simple command."""
subparsers = parser.add_subparsers(title='Title Group A',
# default='qux',
description = desc,
help='some help on group A')
config = self.config
choices = [ ]
for x in [ 'qux', 'fux', 'bux', 'lux' ]:
f = F(x)
kwds = dict( description = "long desc of %s" % x,
# default= 'qux')
p = subparsers.add_parser(, **kwds)
cfg = config.has_section( and dict(config.items( or { }
f.set_parser(p, cfg)
self.commands[] = f
self.pre_parser.add_argument('command', type=str, choices=choices, default='help')
def parse(self, argv):
return self.parser.parse_args(argv)
def run(self, args=None):
remain = None
if args is None:
import sys
args = self.parse(sys.argv[1:])
print 'final pass', pformat(args), pformat(remain)
if hasattr(args, 'run'):, args)
# self.main(self.tool, args)
def main(self, app, params):
# self.tool.main(self, params)
if __name__ == '__main__':
app = Simple() )
import unittest
import argparse
from pprint import pprint
class F(object):
def __init__(self, name): = name
def main(self, app, params):
pprint([, self, params ])
print "Hello, I'm %s." %
def get_simple_parser( ):
parser = argparse.ArgumentParser()
# flesh it out a bit with a no-op option
parser.add_argument('-d', '--debug', action='store_true')
return parser
class TestSubparserDefaultFun(unittest.TestCase):
def setUp(self):
self.parser = get_simple_parser( )
def parse_missing_subcommand_args(self):
def donttest_required_subcommand_behavior(self):
self.parser.parse_args( )
def test_optional_subcommand_behavior(self):
self.parser.parse_args(prep(' '))
def setup_a(parser, name='lalala'):
desc = """This is a long description on a simple command."""
# goal, make qux the default
# default = 'qux'
kwds = dict( title='Title Group A',
description = desc,
prog= "my program",
default = 'qux',
help='some help on group A')
subparsers = parser.add_subparsers(**kwds)
for x in [ 'qux', 'fux', 'bux', 'lux' ]:
f = F(x)
kwds = dict( description = "long desc of %s" % x,
# default= 'qux')
p = subparsers.add_parser(x, **kwds)
def prep(args):
return args.split( )
def main( ):
parser = get_simple_parser( )
#sub = parser.add_subparsers()
#parser.add_argument("paths", "+")
#pprint(parser.parse_args(["foo", "bar"]))
# add some subcommands
if __name__ == '__main__':
unittest.main( )