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.