CLI API Reference

Koji Smoky Dingo - CLI

This package contains mechanisms for more easily adding new command-line features to the Koji client, in coordination with the kojismokydingometa plugin.

author:

Christopher O'Brien <obriencj@gmail.com>

license:

GPL v3

class AdminSmokyDingo(name=None)

Bases: SmokyDingo

A SmokyDingo which checks for the 'admin' permission after activation.

Since:

1.0

Parameters:

name (str) -- The name that this command is being represented as

group: str = 'admin'

The koji CLI group that this command will be displayed under in the help output

permission: str = 'admin'

permission name required for use of this command. A value of None indicates anonymous access.

class AnonSmokyDingo(name=None)

Bases: SmokyDingo

A SmokyDingo which upon activation will connect to koji hub, but will not authenticate. This means only hub RPC endpoints which do not require some permission will work. This is normal for most read-only informational endpoints.

Since:

1.0

Parameters:

name -- The name that this command is being represented as

activate()

Activate our session. This is triggered after validate, before pre_handle and handle

The session and goptions attributes will have been set just prior.

group: str = 'info'

The koji CLI group that this command will be displayed under in the help output

permission: str = None

permission name required for use of this command. A value of None indicates anonymous access.

pre_handle(options)

Verify necessary permissions are in place before attempting any further calls.

exception BadArgument

Bases: BadDingo

Error indicating a bad argument was supplied to a CLI function.

Since:

2.1

complaint: str = 'Bad command argument'

class HostSmokyDingo(name=None)

Bases: SmokyDingo

A SmokyDingo which checks for the 'host' or 'admin' permisson after activation.

Since:

1.0

Parameters:

name (str) -- The name that this command is being represented as

group: str = 'admin'

The koji CLI group that this command will be displayed under in the help output

permission: str = 'host'

permission name required for use of this command. A value of None indicates anonymous access.

class SmokyDingo(name=None)

Bases: CLIProtocol

Base class for new sub-commands in Koji. Subclasses may be referenced via an entry point under the koji_smoky_dingo group to be loaded at runtime by the kojismokydingometa Koji client plugin.

Summary of behavior is as follows

• kojismokydingometa plugin loads when koji client launches

• the meta plugin loads all koji_smoky_dingo entry points

• each entry point name is a command name, and the reference should resolve to a subclass of SmokyDingo

• each entry point is instantiated, and presented to the koji cli as a new sub-command

• if the sub-command is invoked, then the SmokyDingo instance is called, this triggers the following:

  • the SmokyDingo.parser method provides an ArgumentParser instance which it then decorates with arguments by passing it to SmokyDingo.arguments

  • the SmokyDingo.validate method provides a chance to validate and/or manipulate the parsed arguments

  • the SmokyDingo.activate method authenticates with the hub

  • the SmokyDingo.pre_handle method verifies that any required permissions are present for the user

  • the SmokyDingo.handle method invokes the actual work of the sub-command

Since:

1.0

Parameters:

name (str) -- The name that this command is being represented as

activate()

Activate our session. This is triggered after validate, before pre_handle and handle

The session and goptions attributes will have been set just prior.

Return type:

None

arguments(parser)

Override to add relevant arguments to the given parser instance. May return an alternative parser instance or None.

Parameters:

parser (ArgumentParser) -- the parser to decorate with additional arguments

Return type:

ArgumentParser | None

deactivate()

Deactivate our session. This is triggered after handle has completed, either normally or by raising an exception.

The session and goptions attributes will be cleared just after.

Return type:

None

description: str = 'A CLI Plugin'

Short description of this command, for use in the help output

property enabled

get_plugin_config(key, default=None)

fetch a configuration value for this command under the given key. If no configuration is found, returns the default.

Parameters:

• key (str) -- the configuration key name

• default (Any | None) -- value to return if no configuration is found

Return type:

Any

group: str = 'misc'

The koji CLI group that this command will be displayed under in the help output

abstract handle(options)

Perform the full set of actions for this command.

Parameters:

options (Namespace)

Return type:

int | None

parser()

Creates a new ArgumentParser instance and decorates it with arguments from the arguments method.

Return type:

ArgumentParser

permission: str = None

permission name required for use of this command. A value of None indicates anonymous access.

pre_handle(options)

Verify necessary permissions are in place before attempting any further calls.

Parameters:

options (Namespace)

Return type:

None

validate(parser, options)

Override to perform validation on options values. Return value is ignored, use parser.error if needed.

Parameters:

• parser (ArgumentParser)

• options (Namespace)

Return type:

None

class TagSmokyDingo(name=None)

Bases: SmokyDingo

A SmokyDingo which checks for the 'tag' or 'admin' permission after activation.

Since:

1.0

Parameters:

name (str) -- The name that this command is being represented as

group: str = 'admin'

The koji CLI group that this command will be displayed under in the help output

permission: str = 'tag'

permission name required for use of this command. A value of None indicates anonymous access.

class TargetSmokyDingo(name=None)

Bases: SmokyDingo

A SmokyDingo which checks for the 'target' or 'admin' permission after activation.

Since:

1.0

Parameters:

name (str) -- The name that this command is being represented as

group: str = 'admin'

The koji CLI group that this command will be displayed under in the help output

permission: str = 'target'

permission name required for use of this command. A value of None indicates anonymous access.

clean_lines(lines, skip_comments=True)

Filters clean lines from a sequence.

Each line will be stripped of leading and trailing whitespace.

If skip_comments is True (the default), then any line with a leading hash ('#') will be considered a comment and omitted from the output.

Parameters:

• lines (Iterable[str]) -- Sequence of lines to process

• skip_comments (bool) -- Skip over lines with leading # characters. Default, True

Since:

1.0

Return type:

List[str]

convert_history(history)

Converts the history dicts as returned from the ClientSession.queryHistory API into the format print_history expects.

Note that the results are a single list, containing the history from all tables. By default these will be in the order of the table name, then in the order given.

Parameters:

history (Dict[str, List[Dict[str, Any]]]) -- mapping of table name to list of history events

Since:

2.0

Return type:

List[Tuple[int, str, bool, Dict[str, Any]]]

find_action(parser, key)

Hunts through a parser to discover an action whose dest, metavar, or option strings matches the given key.

Parameters:

• parser (ArgumentParser) -- argument parser to search within

• key (str) -- the dest, metavar, or option string of the action

Returns:

the first matching Action, or None

Since:

1.0

Return type:

Action | None

int_or_str(value)

For use as an argument type where the value may be either an int (if it is entirely numeric) or a str.

Since:

1.0

Parameters:

value (Any)

Return type:

int | str

open_output(filename='-', append=None)

Context manager for a CLI output file.

Files will be opened for text-mode output, and closed when the context exits.

If the filename is "-" then stdout will be used as the output file stream, but it will not be closed.

If the filename is "" or None then os.devnull will be used.

If append is True, the file will be appended to. If append is False, the file will be overwritten. If append is None, then the file will be overwriten unless it specified with a prefix of "@". This prefix will be stripped from the filename in this case only.

Since:

1.0

Parameters:

• filename (str)

• append (bool | None)

pretty_json(data, output=None, **pretty)

Presents JSON in a pretty way.

Keyword arguments are passed along to json.dump to alter the default output format defined by JSON_PRETTY_OPTIONS

Parameters:

• data (Any) -- value to be printed

• output (TextIO | None) -- stream to print to. Default, sys.stdout

• pretty -- additional or overriding options to json.dump

Since:

1.0

print_history(timeline, utc=False, show_events=False, verbose=False)

Print history lines using koji's own history formatting. The history timeline needs to be in the format koji is expecting. The results from ClientSession.queryHistory can be converted via the convert_history function.

Parameters:

• timeline (Sequence[Tuple[int, str, bool, Dict[str, Any]]]) -- A sequence of history events to display

• utc (bool) -- output timestamps in UTC instead of local time

• show_events (bool) -- print the individual event IDs

• verbose (bool) -- enables show_events and some additional output

Since:

2.0

print_history_results(timeline, utc=False, show_events=False, verbose=False)

Prints history lines using koji's own history formatting. The history timeline should be in the format as returned by the ClientSession.queryHistory API.

This is a convenience function that combines the convert_history and print_history functions.

Parameters:

• timeline (Dict[str, List[Dict[str, Any]]]) -- A sequence of history events to display

• utc (bool) -- output timestamps in UTC instead of local time

• show_events (bool) -- print the individual event IDs

• verbose (bool) -- enables show_events and some additional output

Since:

2.0

printerr(*values, sep=' ', end='\n', flush=False)

Prints values to stderr by default

Parameters:

• values (Any) -- values to be printed

• sep (str) -- text inserted between values, defaults to a space

• end (str) -- text appended after the last value, defaults to a newline

• flush (bool) -- forcibly flush the stream

Since:

1.0

read_clean_lines(filename='-', skip_comments=True)

Reads clean lines from a named file. If filename is - then read from sys.stdin instead.

Each line will be stripped of leading and trailing whitespace.

If skip_comments is True (the default), then any line with a leading hash ('#') will be considered a comment and omitted from the output.

Content will be fully collected into a list and the file (if not stdin) will be closed before returning.

Parameters:

• filename (str) -- File name to read lines from, or - to indicate stdin. Default, read from sys.stdin

• skip_comments (bool) -- Skip over lines with leading # characters. Default, True

Since:

1.0

Return type:

List[str]

remove_action(parser, key)

Hunts through a parser to remove an action based on the given key. The key can match either the dest, the metavar, or the option strings.

Parameters:

• parser (ArgumentParser) -- argument parser to remove the action from

• key (str) -- value to identify the action by

Since:

1.0

resplit(arglist, sep=',')

Collapses comma-separated and multi-specified items into a single list. Useful with action="append" in an argparse argument.

this allows command-line arguments like

-x 1 -x 2, -x 3,4,5 -x ,6,7, -x 8

to become

x = [1, 2, 3, 4, 5, 6, 7, 8]

Parameters:

• arglist (Iterable[str]) -- original series of arguments to be resplit

• sep (str) -- separator character

Since:

1.0

Return type:

List[str]

space_normalize(txt)

Normalizes the whitespace in txt to single spaces.

Parameters:

txt (str) -- Original text

Since:

1.0

Return type:

str

tabulate(headings, data, key=None, sorting=0, quiet=None, out=None)

Prints tabulated data, with the given headings.

This function is not resilient -- the headings and data must have the same count of rows, nothing will inject empty values.

Output will be configured to set the columns to their maximum width necessary for the longest value from all the rows or the heading.

Parameters:

• headings (Sequence[str]) -- The column titles

• data (Any) -- Rows of data

• key (Callable[[Any], Tuple] | List | Tuple | None) -- Transformation to apply to each row of data to get the actual individual columns. Should be a unary function. Default, data is iterated as-is.

• sorting (int) -- Whether data rows should be sorted and in what direction. 0 for no sorting, 1 for ascending, -1 for descending. If key is specified, then sorting will be based on those transformations. Default, no sorting.

• quiet (bool | None) -- Whether to print headings or not. Default, only print headings if out is a TTY device.

• out (TextIO | None) -- Stream to write output to. Default, sys.stdout

Since:

1.0

CLI Modules

• kojismokydingo.cli.archives
• kojismokydingo.cli.builds
• kojismokydingo.cli.clients
• kojismokydingo.cli.hosts
• kojismokydingo.cli.tags
• kojismokydingo.cli.sift
• kojismokydingo.cli.users