From 4de2e6dc6e8503ade36c2b3e9315b29234c467ff Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Sun, 30 Jun 2024 20:26:25 -0500 Subject: [PATCH] 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 --- docs/glossary.rst | 10 +-- docs/index.rst | 2 - docs/narr/cli/commands.rst | 127 ++++------------------------------ docs/narr/cli/index.rst | 1 - docs/narr/cli/overview.rst | 18 ++--- docs/narr/cli/subcommands.rst | 92 ------------------------ src/wuttjamaican/cmd/base.py | 4 +- 7 files changed, 25 insertions(+), 229 deletions(-) delete mode 100644 docs/narr/cli/subcommands.rst diff --git a/docs/glossary.rst b/docs/glossary.rst index 1b27d73..0237131 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -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`. 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 diff --git a/docs/index.rst b/docs/index.rst index 85fec18..3da6f92 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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`_ diff --git a/docs/narr/cli/commands.rst b/docs/narr/cli/commands.rst index 66445d4..b04d0b2 100644 --- a/docs/narr/cli/commands.rst +++ b/docs/narr/cli/commands.rst @@ -2,122 +2,21 @@ Commands ======== -Top-level :term:`commands` are primarily a way to group -:term:`subcommands`. +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` and :term:`subcommands` as +needed: -.. _running-commands: +* `Typer `_ +* `Click `_ +* :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 `_ +* `Python Wiki `_ -.. 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)` 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`. diff --git a/docs/narr/cli/index.rst b/docs/narr/cli/index.rst index 66fe405..2070234 100644 --- a/docs/narr/cli/index.rst +++ b/docs/narr/cli/index.rst @@ -7,5 +7,4 @@ Command Line Interface overview commands - subcommands scripts diff --git a/docs/narr/cli/overview.rst b/docs/narr/cli/overview.rst index 0589f38..df69f9c 100644 --- a/docs/narr/cli/overview.rst +++ b/docs/narr/cli/overview.rst @@ -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` -and :term:`subcommands`; 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` and :term:`subcommands`, which +are then installed as part of a package. See :doc:`commands` for more +about that. diff --git a/docs/narr/cli/subcommands.rst b/docs/narr/cli/subcommands.rst deleted file mode 100644 index 3df761f..0000000 --- a/docs/narr/cli/subcommands.rst +++ /dev/null @@ -1,92 +0,0 @@ - -Subcommands -=========== - -A top-level :term:`command` may have multiple -:term:`subcommands`. - -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 diff --git a/src/wuttjamaican/cmd/base.py b/src/wuttjamaican/cmd/base.py index deeb763..50d96d8 100644 --- a/src/wuttjamaican/cmd/base.py +++ b/src/wuttjamaican/cmd/base.py @@ -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