wutta/wuttjamaican
3
0
Fork 0
Code Activity

docs: stop documenting wutta command line framwework

Browse source 
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 2024-06-30 20:26:25 -05:00
parent 746bcf18de
commit 4de2e6dc6e
7 changed files with 25 additions and 229 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/glossary.rst
View file

@ -53,9 +53,9 @@ Glossary
command command
A top-level command line interface for the app. Note that 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 mostly a way to group :term:`subcommands<subcommand>`. See also
:class:`~wuttjamaican.cmd.base.Command`. :doc:`narr/cli/index`.
config config
Depending on context, may refer to any of: :term:`config file`, Depending on context, may refer to any of: :term:`config file`,
@ -120,9 +120,9 @@ Glossary
subcommand subcommand
A top-level :term:`command` may expose one or more subcommands, A top-level :term:`command` may expose one or more subcommands,
for the overall command line interface. Subcommands are the real for the overall command line interface. Subcommands are usually
workhorse; each can perform a different function. See also the real workhorse; each can perform a different function. See
:doc:`narr/cli/subcommands`. also :doc:`narr/cli/index`.
virtual environment virtual environment
This term comes from the broader Python world and refers to an This term comes from the broader Python world and refers to an

2
docs/index.rst
View file

@ -30,8 +30,6 @@ Features
-------- --------
* flexible configuration, using config files and/or DB settings table * 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 architecture, abstracting various portions of the overall app
* flexible database support, using `SQLAlchemy`_ * flexible database support, using `SQLAlchemy`_

127
docs/narr/cli/commands.rst
View file

@ -2,122 +2,21 @@
Commands Commands
======== ========
Top-level :term:`commands<command>` are primarily a way to group WuttJamaican in fact does not directly provide a way to define a
:term:`subcommands<subcommand>`. 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 * `awesome-cli-framework <https://github.com/shadawck/awesome-cli-frameworks/blob/master/README.md#python>`_
within the ``bin`` folder of the virtual environment. (Or the * `Python Wiki <https://wiki.python.org/moin/CommandlineTools>`_
``Scripts`` folder if on Windows.) For instance:
.. code-block:: sh Or if that is overkill you can always just use :doc:`scripts`.
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`.

1
docs/narr/cli/index.rst
View file

@ -7,5 +7,4 @@ Command Line Interface
overview overview
commands commands
subcommands
scripts scripts

18
docs/narr/cli/overview.rst
View file

@ -2,20 +2,14 @@
Overview Overview
======== ========
The command line interface is an important part of app automation and Many apps will need some sort of command line usage, via cron or
may be thought of in a couple ways: otherwise. There are two main aspects to it:
First there is the :term:`ad hoc script` which is a single file and 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 can be placed anywhere, but is not installed as part of a
:term:`package`. See :doc:`scripts`. :term:`package`. See :doc:`scripts`.
But the "real" command line interface uses :term:`commands<command>` But a "true" command line interface may define
and :term:`subcommands<subcommand>`; these are installed as part of a :term:`commands<command>` and :term:`subcommands<subcommand>`, which
package. are then installed as part of a package. See :doc:`commands` for more
about that.
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.

92
docs/narr/cli/subcommands.rst
View file

@ -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

4
src/wuttjamaican/cmd/base.py
View file

@ -2,7 +2,7 @@
################################################################################ ################################################################################
# #
# WuttJamaican -- Base package for Wutta Framework # WuttJamaican -- Base package for Wutta Framework
# Copyright © 2023 Lance Edgar # Copyright © 2023-2024 Lance Edgar
# #
# This file is part of Wutta Framework. # This file is part of Wutta Framework.
# #
@ -336,8 +336,6 @@ class Subcommand:
*only* a base class.) For a real example see *only* a base class.) For a real example see
:class:`~wuttjamaican.cmd.make_appdir.MakeAppDir`. :class:`~wuttjamaican.cmd.make_appdir.MakeAppDir`.
For more info see :doc:`/narr/cli/subcommands`.
.. attribute:: stdout .. attribute:: stdout
Reference to file-like object which should be used for writing Reference to file-like object which should be used for writing