CLI internals

The cotainr command line interface is designed around a subcommand for each major action, cotainr provides. Each subcommand then supports a set of options. They all support --help for displaying a help message.

The CLI is build using argparse.

The main way to invoke the CLI (sub)commands is via the bin/cotainr script, e.g.

$ ./bin/cotainr build <positional_arg> <non-positional args>
$ ./bin/cotainr info

Implementation of command line interface

The command line interface is implemented in the cotainr.cli module. It consists of the CotainrCLI class that implements the main CLI command. When instantiated, it exposes the following two attributes:

• args: A types.SimpleNamespace containing the parsed CLI arguments.

• subcommand: An instance of the subcommand class that is requested when the script was invoked.

The CotainrCLI class is intended to be used as:

cli = CotainrCLI()
cli.subcommand.execute()

Each of the subcommands is implemented as a separate subclass of the CotainrSubcommand class which defines the following interface:

• __init__(): Constructor that assigns all parameters as instance attributes and performs any check/verification and parsing of the parameters beyond simple checks and parsing implemented by the argparse.ArgumentParser.add_argument() method.

• add_arguments(): Classmethod that implements the relevant argparse.ArgumentParser.add_argument() CLI arguments corresponding to the constructor arguments.

• execute(): Method that does whatever it entails to run the subcommand.

In order to add a new subcommand, one has to:

• Implement a class that:

  • Is named as the desired subcommand name.

  • Implements the above subcommands interface.

• Add the class to the cotainr.cli.CotainrCLI._subcommands class attribute.

This implementation was inspired by Satya Sai Vineeth Guna’s cli_design.py.

Throughout the implementation, we try to avoid repeating (in the source code) help messages for the CLI by (ab)using the __doc__ dunder to automatically extract such help messages from a single place of definition. That is, the text shown when running cotainr --help, cotainr build --help, etc. is automatically extracted from the docstrings of the classes implementing those (sub)commands. Specifically, we automatically extract:

• The main CLI description text from the CotainrCLI class docstring short summary.

• The subcommands description and help summary from their class docstring short summary, e.g. for the cotainr build subcommand we extract it from the Build class docstring.

• The subcommands help texts from the Parameters section in their class docstring. For easing this, we have the cotainr.cli._extract_help_from_docstring() function. Note that this utility function relies on the assumption that the docstrings are formatted according to the numpydoc format.