upsies.uis.tui.commands.base

Abstract base class for commands

Functions

upsies.uis.tui.commands.base.PrintText(text_getter)

Print text returned by callable and exit with exit code 0

Parameters:

text_getter – Callable that takes no arguments and returns the text to print

Classes

class upsies.uis.tui.commands.base.CommandBase(args, config)

Bases: ABC

Base class for all commands

register() must be called on all subclasses.

Instead of instantiating subclasses normally, the class method run() should be used to get instances.

Parameters:

• args – Command line arguments

• config – ConfigBase object

names = NotImplemented

Sequence of command names

The first name is the full name and the rest are short aliases.

description = ''

Extended description

The class docstring is the main description. Use this class attribute to generate text programmatically.

cli_arguments = NotImplemented

CLI argument definitions for this command

This is a dict in which keys are option names or flags (e.g. "PATH" or ("--path", "-p") and each value is a dict with keyword arguments for argparse.ArgumentParser.add_argument().

Additionally, you may specify a group in each keyword argument dictionary. Arguments with the same group value are mutually exclusive, meaning the user can only specify one of them.

subcommands = {}

Subcommands of commands (or subsubcommands from a CLI point of view)

This is a dict where keys are subcommand names and values are cli_arguments.

subcommand_descriptions = {}

Descriptions of subcommands

For each key in subcommands, this dict may provide a longer multiline (or even multiparagraph) description.

subcommand_name = 'PLEASE_GIVE_THIS_SUBCOMMAND_A_PROPER_METAVAR'

Reference to expected subcommand in help texts

classmethod register()

Add the command and its arguments to the internal argparse.ArgumentParser instance

This classmethod must be called on every subclass.

classmethod run(args)

Execute command

Parameters:

args – Sequence of CLI arguments or None to use sys.argv

abstract property jobs

Iterable of JobBase instances

Each JobBase instance may also be None for inactive jobs.

property jobs_active

Same as jobs but without None values

property main_job

The main job in jobs_active

This job’s output is the output of the command.

In the default implementation, this is the last job in jobs_active that is_enabled.

property args

Parsed CLI arguments as argparse.Namespace object

property config

Config file options as ConfigBase object

get_options(section_name, subsection_name)

Combine section in config file with CLI arguments

CLI arguments take precedence unless their value is None.

Parameters:

• section_name (str) – Config file name with out the “INI” extension

• subsection_name (str) – Name of a section in the config file

Returns:

dict

property home_directory

Passed as home_directory argument to jobs.base.JobBase instances that are instantiated by this class

The default implementation passes the CONTENT or RELEASE argument and config.main.cache_directory to fs.projectdir().

If no CONTENT or RELEASE argument exists, return config.main.cache_directory directly.

property cache_directory

Passed as cache_directory argument to jobs.base.JobBase instances that are instantiated by this class

The default implementation returns home_directory (e.g. ~/.cache/upsies/Foo.2012-ASDF.upsies/) if the CONTENT or RELEASE argument exists and returns config.main.cache_directory otherwise.