Subcommands

A top-level command may have multiple subcommands.

The top-level command is responsible for invoking the subcommand, but the subcommand is responsible for performing some action(s).

There is no restriction on what sort of action that might be, but for sake of clarity it is best to make a distinct subcommand for each “type” of action needed by the app.

Running a Subcommand

You cannot run a subcommand directly; you must run a top-level command and specify the subcommand as part of the command line arguments. See Running a Command.

This restriction holds true even when running a subcommand “natively” from within Python code. For more info see wuttjamaican.cmd.base.Subcommand.run().

Built-in Subcommands

WuttJamaican comes with one top-level command named wutta as well as a few subcommands under that.

See wuttjamaican.cmd for more on the built-in wutta subcommands.

Adding a New Subcommand

There are two steps for this:

• define the subcommand

• register it under top-level command(s)

First create a Subcommand class (e.g. by adding to poser/commands.py):

from wuttjamaican.cmd import Subcommand

class Hello(Subcommand):
    """
    Say hello to the user
    """
    name = 'hello'
    description = __doc__.strip()

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

    def run(self, args):
        print("hello, foo value is:", args.foo)

You may notice there is nothing in that subcommand definition which ties it to the poser top-level command. That is done by way of another entry point in your setup.cfg file.

As with top-level commands, you can “alias” the same subcommand so it appears under multiple top-level commands. Note that if the top-level command name contains a hyphen, that must be replaced with underscore for sake of the subcommand entry point:

[options.entry_points]

poser.subcommands =
    hello = poser.commands:Hello

wutta_poser.subcommands =
    hello = poser.commands:Hello

Next time your poser package is installed, the subcommand will be available, so you can e.g.:

cd /path/to/venv
bin/poser hello --help
bin/wutta-poser hello --help