TheCli
This is the developer documentation for the viewser CLI. viewser is a
fully-fledged toolkit for using all Views 3 has to offer. This documentation
describes the structure and design choices of the tool, to make it easy to
develop extensions and new features.
viewser is based on the excellent
Click library.
The CLI exposed by viewser is located in the viewser package under
viewser.cli:viewser. This function is a command group that includes various
sub-groups located in modules under the commands module, like
commands.config.cli and commands.queryset.cli. Each subgroup has its own
module, which is isolated from the other subgroups as much as possible, making
changes risk-free.
Some common classes are also offered, providing useful functionality like
output formatting (viewser.tui) and safer web requests (viewser.remotes).
Typically, a command performs an action, and displays some output. Between the
different command groups, the actions performed vary from making API requests
(viewser queryset / viewser tables / transforms), to altering the
configuration database (located at ~/.views/settings.sqlite, manipulated by
viewser config). Commands with similar functionality often share code, such
as the monadic requests code used by both the queryset module and the
documentation module(s) for making safe requests.
Most commands share output functionality via the viewser.tui module, provided
via the Formatter and Section classes. The purpose of these classes is to
provide consistent output, making all commands "feel" the same. Importantly,
the Section class works on pydantic models, which means that each command
should define or depend upon a set of models for display. This pairs well with
the purpose of pydantic models as protocol for communicating with backend
services; viewser often serializes the data returned from APIs directly.
To add a command, create a new module (file, or folder with __init__.py) in
the viewser/commands folder, and add a file called cli.py. In this file,
define a function cli that is decorated either as a group (for further
subcommands) or as a command (see the excellent
Click documentation
for further documentation on how commands / groups can be customized).
If your command has functionality that is shared by other commands, you might
want to use some of the shared code found in the viewser package, like the
requests logic in the remotes module. In any case, output should be formatted
by a viewser.tui.formatting.abc.Formatter subclass. This means that your
commands' operations should at some point produce a Pydantic model.