docs: stop documenting wutta command line framwework
as we will be deprecating and removing it at some point. `typer` seems to work well but any other framework could be used
This commit is contained in:
Lance Edgar
parent
746bcf18de
commit
4de2e6dc6e
|
|
@ -53,9 +53,9 @@ Glossary
|
|||
|
||||
command
|
||||
A top-level command line interface for the app. Note that
|
||||
top-level commands don't really "do" anything per se, and are
|
||||
top-level commands don't usually "do" anything per se, and are
|
||||
mostly a way to group :term:`subcommands<subcommand>`. See also
|
||||
:class:`~wuttjamaican.cmd.base.Command`.
|
||||
:doc:`narr/cli/index`.
|
||||
|
||||
config
|
||||
Depending on context, may refer to any of: :term:`config file`,
|
||||
|
|
@ -120,9 +120,9 @@ Glossary
|
|||
|
||||
subcommand
|
||||
A top-level :term:`command` may expose one or more subcommands,
|
||||
for the overall command line interface. Subcommands are the real
|
||||
workhorse; each can perform a different function. See also
|
||||
:doc:`narr/cli/subcommands`.
|
||||
for the overall command line interface. Subcommands are usually
|
||||
the real workhorse; each can perform a different function. See
|
||||
also :doc:`narr/cli/index`.
|
||||
|
||||
virtual environment
|
||||
This term comes from the broader Python world and refers to an
|
||||
|
|
|
|||
|
|
@ -30,8 +30,6 @@ Features
|
|||
--------
|
||||
|
||||
* flexible configuration, using config files and/or DB settings table
|
||||
* flexible command line interface, with arbitrary top-level and
|
||||
subcommands
|
||||
* flexible architecture, abstracting various portions of the overall app
|
||||
* flexible database support, using `SQLAlchemy`_
|
||||
|
||||
|
|
|
|||
|
|
@ -2,122 +2,21 @@
|
|||
Commands
|
||||
========
|
||||
|
||||
Top-level :term:`commands<command>` are primarily a way to group
|
||||
:term:`subcommands<subcommand>`.
|
||||
WuttJamaican in fact does not directly provide a way to define a
|
||||
command line interface for your app.
|
||||
|
||||
The reason is that several good frameworks exist already. You are
|
||||
encouraged to use one of the following to define
|
||||
:term:`commands<command>` and :term:`subcommands<subcommand>` as
|
||||
needed:
|
||||
|
||||
.. _running-commands:
|
||||
* `Typer <https://typer.tiangolo.com/>`_
|
||||
* `Click <https://click.palletsprojects.com/en/latest/>`_
|
||||
* :mod:`python:argparse`
|
||||
|
||||
Running a Command
|
||||
-----------------
|
||||
For even more options see:
|
||||
|
||||
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:
|
||||
* `awesome-cli-framework <https://github.com/shadawck/awesome-cli-frameworks/blob/master/README.md#python>`_
|
||||
* `Python Wiki <https://wiki.python.org/moin/CommandlineTools>`_
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
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.:
|
||||
|
||||
.. 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-commands:
|
||||
|
||||
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 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:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[options.entry_points]
|
||||
console_scripts =
|
||||
poser = poser.commands:poser_main
|
||||
wutta-poser = poser.commands:wutta_poser_main
|
||||
|
||||
Next time your ``poser`` :term:`package` is installed, the command
|
||||
will be available:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
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 :ref:`adding-subcommands`.
|
||||
Or if that is overkill you can always just use :doc:`scripts`.
|
||||
|
|
|
|||
|
|
@ -7,5 +7,4 @@ Command Line Interface
|
|||
|
||||
overview
|
||||
commands
|
||||
subcommands
|
||||
scripts
|
||||
|
|
|
|||
|
|
@ -2,20 +2,14 @@
|
|||
Overview
|
||||
========
|
||||
|
||||
The command line interface is an important part of app automation and
|
||||
may be thought of in a couple ways:
|
||||
Many apps will need some sort of command line usage, via cron or
|
||||
otherwise. There are two main aspects to it:
|
||||
|
||||
First there is the :term:`ad hoc script` which is a single file and
|
||||
can be placed anywhere, but is not installed as part of a
|
||||
:term:`package`. See :doc:`scripts`.
|
||||
|
||||
But the "real" command line interface uses :term:`commands<command>`
|
||||
and :term:`subcommands<subcommand>`; these are installed as part of a
|
||||
package.
|
||||
|
||||
Top-level commands are mostly just a way to group subcommands. Most
|
||||
custom apps would define their own top-level command as well as
|
||||
multiple subcommands. See :doc:`commands` for top-level details.
|
||||
|
||||
Subcommands on the other hand are the real workhorse since they define
|
||||
the action logic. See :doc:`subcommands` for more about those.
|
||||
But a "true" command line interface may define
|
||||
:term:`commands<command>` and :term:`subcommands<subcommand>`, which
|
||||
are then installed as part of a package. See :doc:`commands` for more
|
||||
about that.
|
||||
|
|
|
|||
|
|
@ -1,92 +0,0 @@
|
|||
|
||||
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
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
################################################################################
|
||||
#
|
||||
# WuttJamaican -- Base package for Wutta Framework
|
||||
# Copyright © 2023 Lance Edgar
|
||||
# Copyright © 2023-2024 Lance Edgar
|
||||
#
|
||||
# This file is part of Wutta Framework.
|
||||
#
|
||||
|
|
@ -336,8 +336,6 @@ class Subcommand:
|
|||
*only* a base class.) For a real example see
|
||||
:class:`~wuttjamaican.cmd.make_appdir.MakeAppDir`.
|
||||
|
||||
For more info see :doc:`/narr/cli/subcommands`.
|
||||
|
||||
.. attribute:: stdout
|
||||
|
||||
Reference to file-like object which should be used for writing
|
||||
|
|
|
|||
Loading…
Reference in a new issue