112 lines
2.8 KiB
ReStructuredText
112 lines
2.8 KiB
ReStructuredText
|
|
||
|
Commands
|
||
|
========
|
||
|
|
||
|
Top-level :term:`commands<command>` are primarily a way to group
|
||
|
:term:`subcommands<subcommand>`.
|
||
|
|
||
|
|
||
|
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.)
|
||
|
|
||
|
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.:
|
||
|
|
||
|
.. code-block:: sh
|
||
|
|
||
|
wutta --help
|
||
|
|
||
|
To actually *do* anything you must also specify a subcommand, e.g.:
|
||
|
|
||
|
.. code-block:: sh
|
||
|
|
||
|
wutta make-appdir
|
||
|
|
||
|
Many subcommands may accept arguments of their own:
|
||
|
|
||
|
.. code-block:: sh
|
||
|
|
||
|
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:
|
||
|
|
||
|
.. code-block:: sh
|
||
|
|
||
|
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:
|
||
|
|
||
|
.. code-block:: sh
|
||
|
|
||
|
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 :mod:`wuttjamaican.cmd` for more on the built-in ``wutta``
|
||
|
subcommands.
|
||
|
|
||
|
.. command-output:: wutta -h
|
||
|
:returncode: 1
|
||
|
|
||
|
|
||
|
Adding a New Command
|
||
|
--------------------
|
||
|
|
||
|
There is not much to this since top-level commands are mostly just a
|
||
|
grouping mechanism.
|
||
|
|
||
|
First create your :class:`~wuttjamaican.cmd.base.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 :term:`entry point(s)<entry point>` in your
|
||
|
``setup.cfg``. The command name should not contain spaces but may
|
||
|
include hyphens or underscore etc.
|
||
|
|
||
|
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:
|
||
|
|
||
|
.. code-block:: ini
|
||
|
|
||
|
[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:
|
||
|
|
||
|
.. code-block:: sh
|
||
|
|
||
|
cd /path/to/venv
|
||
|
bin/poser --help
|
||
|
bin/wutta-poser --help
|