wuttjamaican.cmd.base

WuttJamaican - command framework

class wuttjamaican.cmd.base.Command(config=None, name=None, stdout=None, stderr=None, subcommands=None)

Primary command for the application.

A primary command will usually have multiple subcommands it can run. The typical command line interface is like:

<command> [command-options] <subcommand> [subcommand-options]

Subcommand will contain most of the logic, in terms of what actually happens when it runs. Top-level commands are mostly a stub for sake of logically grouping the subcommands.

Parameters:

• config –

  Optional config object to use.

  Usually a command is being ran via actual command line, and there is no config object yet so it must create one. (It does this within its run() method.)

  But if you already have a config object you can specify it here and it will be used instead.

• name – Optional value to assign to name. Usually this is declared within the command class definition, but if needed it can be provided dynamically.

• stdout – Optional replacement to use for stdout.

• stderr – Optional replacement to use for stderr.

• subcommands – Optional dictionary to use for subcommands, instead of loading those via entry points.

This base class also serves as the primary wutta command for WuttJamaican. Most apps will subclass this and register their own top-level command, then create subcommands as needed.

For more info see Commands.

name

Name of the primary command, e.g. wutta

description

Description of the app itself or the primary command.

version

Version string for the app or primary command.

stdout

Reference to file-like object which should be used for writing to STDOUT. By default this is just sys.stdout.

stderr

Reference to file-like object which should be used for writing to STDERR. By default this is just sys.stderr.

subcommands

Dictionary of available subcommand classes, keyed by subcommand name. These are usually loaded from setuptools entry points.

add_args()

Configure args for the main command arg parser.

Anything you setup here will then be available when the command runs. You can add arguments directly to self.parser, e.g.:

self.parser.add_argument('--foo', default='bar', help="Foo value")

See also docs for argparse.ArgumentParser.add_argument().

make_arg_parser()

Must return a new argparse.ArgumentParser instance for use by the main command.

This will use CommandArgumentParser by default.

make_config(args)

Make the config object in preparation for running a subcommand.

By default this is a straightforward wrapper around wuttjamaican.conf.make_config().

Returns:

The new config object.

prep_subcommand(subcommand, args)

Prepare the subcommand for running, as needed.

print_help()

Print usage help text for the main command.

run(*args)

Parse command line arguments and execute appropriate subcommand.

Or, if requested, or args are ambiguous, show help for either the top-level or subcommand.

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you must specify the full command line args except not the top-level command name. So for example to run the equivalent of this command line:

wutta setup --help

You could do this in Python:

from wuttjamaican.cmd import Command

cmd = Command()
assert cmd.name == 'wutta'
cmd.run('setup', '--help')

sorted_subcommands()

Get the list of subcommand classes, sorted by name.

class wuttjamaican.cmd.base.CommandArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Custom argument parser for use with Command.

This is based on standard argparse.ArgumentParser but overrides some of the parsing logic which is specific to the primary command object, to separate command options from subcommand options.

This is documented as FYI but you probably should not need to know about or try to use this yourself. It will be used automatically by Command or a subclass thereof.

class wuttjamaican.cmd.base.Subcommand(command)

Base class for application subcommands.

Subcommands are where the real action happens. Each must define the run() method with whatever logic is needed. They can also define add_args() to expose options.

Subcommands always belong to a top-level command - the association is made by way of entry point registration, and the constructor for this class.

Parameters:

command – Reference to top-level Command object.

Note that unlike Command, the base Subcommand does not correspond to any real subcommand for WuttJamaican. (It’s only a base class.) For a real example see MakeAppDir.

For more info see Subcommands.

stdout

Reference to file-like object which should be used for writing to STDOUT. This is inherited from Command.stdout.

stderr

Reference to file-like object which should be used for writing to STDERR. This is inherited from Command.stderr.

add_args()

Configure additional args for the subcommand arg parser.

Anything you setup here will then be available within run(). You can add arguments directly to self.parser, e.g.:

self.parser.add_argument('--foo', default='bar', help="Foo value")

See also docs for argparse.ArgumentParser.add_argument().

make_arg_parser()

Must return a new argparse.ArgumentParser instance for use by the subcommand.

print_help()

Print usage help text for the subcommand.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

wuttjamaican.cmd.base.main(*args)

Primary entry point for the wutta command.