TheCli

Developing the CLI

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.

Structure

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.

Adding a command

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.