Commands

Top-level commands are primarily a way to group subcommands.

Running a Command

Top-level commands are installed in such a way that they are available within the bin folder of the virtual environment. (Or the Scripts folder if on Windows.) For instance:

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

This folder should be in the PATH when the virtual environment is activated, in which case you can just run the command by name, e.g.:

wutta --help

To actually do anything you must also specify a subcommand, e.g.:

wutta make-appdir

Many subcommands may accept arguments of their own:

wutta make-appdir --path=/where/i/want/my/appdir

But top-level commands also accept global arguments. See the next section for the full list of “global” command options. A complete example then might be like:

wutta --config=/path/to/my/file.conf make-appdir --path=/where/i/want/my/appdir

Note that the top-level command will parse its global option args first, and give only what’s leftover to the subcommand. Therefore it isn’t strictly necessary to specify global options before the subcommand:

wutta make-appdir --path=/where/i/want/my/appdir --config=/path/to/my/file.conf

wutta command

WuttJamaican comes with one top-level command named wutta. Note that the list of available subcommands is shown in the top-level command help.

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

$ wutta -h
usage: wutta [options] <subcommand> [subcommand-options]

Wutta Software Framework

options:
  -c PATH, --config PATH
                        Config path (may be specified more than once)
  --plus-config PATH    Extra configs to load in addition to normal config
  -P, --progress        Report progress when relevant
  -V, --version         show program's version number and exit
  --stdout PATH         Optional path to which STDOUT should be written
  --stderr PATH         Optional path to which STDERR should be written

subcommands:
  date-organize         Organize files into subfolders according to date
  make-appdir           Make or refresh the "app dir" for virtual environment
  setup                 Install and configure various software

also try: wutta <subcommand> -h

Adding a New Command

There is not much to this since top-level commands are mostly just a grouping mechanism.

First create your Command class, and a main() function for it (e.g. in poser/commands.py):

import sys
from wuttjamaican.cmd import Command

class PoserCommand(Command):
    name = 'poser'
    description = 'my custom top-level command'
    version = '0.1'

def poser_main(*args):
    args = list(args) or sys.argv[1:]
    cmd = PoserCommand()
    cmd.run(*args)

Then register the entry point(s) in your setup.cfg. The command name should not contain spaces but may include hyphen or underscore.

You can register more than one top-level command if needed; these could refer to the same main() function (in which case they are really aliases) or can use different functions:

[options.entry_points]
console_scripts =
    poser = poser.commands:poser_main
    wutta-poser = poser.commands:wutta_poser_main

Next time your poser package is installed, the command will be available:

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

You will then likely want to add subcommand(s) for this to be useful; see Adding a New Subcommand.