93 lines
2.4 KiB
ReStructuredText
93 lines
2.4 KiB
ReStructuredText
|
|
Subcommands
|
|
===========
|
|
|
|
A top-level :term:`command` may have multiple
|
|
:term:`subcommands<subcommand>`.
|
|
|
|
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
|
|
:ref:`running-commands`.
|
|
|
|
This restriction holds true even when running a subcommand "natively"
|
|
from within Python code. For more info see
|
|
:meth:`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 :mod:`wuttjamaican.cmd` for more on the built-in ``wutta``
|
|
subcommands.
|
|
|
|
|
|
.. _adding-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 :term:`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:
|
|
|
|
.. code-block:: ini
|
|
|
|
[options.entry_points]
|
|
|
|
poser.subcommands =
|
|
hello = poser.commands:Hello
|
|
|
|
wutta_poser.subcommands =
|
|
hello = poser.commands:Hello
|
|
|
|
Next time your ``poser`` :term:`package` is installed, the subcommand
|
|
will be available, so you can e.g.:
|
|
|
|
.. code-block:: sh
|
|
|
|
cd /path/to/venv
|
|
bin/poser hello --help
|
|
bin/wutta-poser hello --help
|