COT.helpers.helper module

Common interface for providers of non-Python helper programs.

Provides the ability to install the program if not already present, and the ability to run the program as well.

Classes

HelperNotFoundError	A helper program cannot be located.
HelperError	A helper program exited with non-zero return code.
Helper	A provider of a non-Python helper program.
PackageManager	Helper program with additional API method install_package().

Attributes

helpers

Dictionary of concrete Helper subclasses to be populated at load time.

Functions

check_call	Wrapper for subprocess.check_call().
check_output	Wrapper for subprocess.check_output().

exception HelperError

Bases: exceptions.EnvironmentError

A helper program exited with non-zero return code.

exception HelperNotFoundError

Bases: exceptions.OSError

A helper program cannot be located.

class Helper(name, info_uri=None, version_args=None, version_regexp='([0-9.]+)')

Bases: object

A provider of a non-Python helper program.

Static Methods

cp	Copy the given src to the given dest, using sudo if needed.
download_and_expand_tgz	Context manager for downloading and expanding a .tar.gz file.
mkdir	Check whether the given target directory exists, and create if not.

Instance Properties

name	Name of the helper program.
info_uri	URI for more information about this helper.
installable	Whether COT is capable of installing this program on this system.
installed	Whether this helper program is installed and available to run.
path	Discovered path to the helper.
version	Release version of the associated helper program.

Instance Methods

call	Call the helper program with the given arguments.
install	Install the helper program.
unsure_how_to_install	Raise a NotImplementedError about missing install logic.

__init__(name, info_uri=None, version_args=None, version_regexp='([0-9.]+)')

Initializer.

Parameters:

• name (str) – Name of helper executable
• info_uri (str) – URI to refer to for more info about this helper.
• version_args (list) – Args to pass to the helper to get its version. Defaults to ['--version'] if unset.
• version_regexp (str) – Regexp to get the version number from the output of the command.

call(args, capture_output=True, **kwargs)

Call the helper program with the given arguments.

Parameters:

• args (list) – List of arguments to the helper program.
• capture_output (boolean) – If True, stdout/stderr will be redirected to a buffer and returned, instead of being displayed to the user. (I.e., check_output() will be invoked instead of check_call())

Returns:

str – Captured stdout/stderr if capture_output is True, else None.

For the other parameters, see check_call() and check_output().

Raises:HelperNotFoundError – if the helper was not previously installed, and the user declines to install it at this time.

static cp(src, dest)

Copy the given src to the given dest, using sudo if needed.

Parameters:

• src (str) – Source path.
• dest (str) – Destination path.

Returns:

bool – True

Raises:

HelperError – if file copying fails

static download_and_expand_tgz(*args, **kwds)

Context manager for downloading and expanding a .tar.gz file.

Creates a temporary directory, downloads the specified URL into the directory, unzips and untars the file into this directory, then yields to the given block. When the block exits, the temporary directory and its contents are deleted.

with download_and_expand_tgz("http://example.com/foo.tgz") as d:
    # archive contents have been extracted to 'd'
    ...
# d is automatically cleaned up.

Parameters:url (str) – URL of a .tgz or .tar.gz file to download. Yields:str – Temporary directory path where the archive has been extracted.

install()

Install the helper program.

Raises:

• NotImplementedError – if not installable
• HelperError – if installation is attempted but fails.

Subclasses should not override this method but instead should provide an appropriate implementation of the _install() method.

static mkdir(directory, permissions=493)

Check whether the given target directory exists, and create if not.

Parameters:

• directory (str) – Directory to check/create.
• permissions (int) – Permission mask to set when creating a directory. Default is 0o755.

unsure_how_to_install()

Raise a NotImplementedError about missing install logic.

USER_INTERFACE = <COT.cli.CLI object>

User interface (if any) available to helpers.

info_uri

URI for more information about this helper.

installable

Whether COT is capable of installing this program on this system.

installed

Whether this helper program is installed and available to run.

name

Name of the helper program.

path

Discovered path to the helper.

version

Release version of the associated helper program.

class HelperDict(factory, *args, **kwargs)

Bases: dict

Dictionary of Helper objects by name.

Similar to collections.defaultdict but takes the key as a parameter to the factory.

__init__(factory, *args, **kwargs)

Create the given dictionary with the given factory class/method.

Parameters:factory (object) – Factory class or method to be called to populate a new entry in response to __missing__().

For the other parameters, see dict.

class PackageManager(name, info_uri=None, version_args=None, version_regexp='([0-9.]+)')

Bases: COT.helpers.helper.Helper

Helper program with additional API method install_package().

install_package(package)

Install the requested package if needed.

Parameters:package (str) – Name of the package to install.

check_call(args, require_success=True, retry_with_sudo=False, **kwargs)

Wrapper for subprocess.check_call().

Unlike check_output() below, this does not redirect stdout or stderr; all output from the subprocess will be sent to the system stdout/stderr as normal.

Parameters:

• args (list) – Command to invoke and its associated args
• require_success (boolean) – If False, do not raise an error when the command exits with a return code other than 0
• retry_with_sudo (boolean) – If True, if the command gets an exception, prepend sudo to the command and try again.

For the other parameters, see subprocess.check_call().

Raises:

• HelperNotFoundError – if the command doesn’t exist (instead of a OSError)
• HelperError – if require_success is not False and the command returns a value other than 0 (instead of a subprocess.CalledProcessError).
• OSError – as subprocess.check_call().

check_output(args, require_success=True, retry_with_sudo=False, **kwargs)

Wrapper for subprocess.check_output().

Automatically redirects stderr to stdout, captures both to a buffer, and generates a debug message with the stdout contents.

Parameters:

• args (list) – Command to invoke and its associated args
• require_success (boolean) – If False, do not raise an error when the command exits with a return code other than 0
• retry_with_sudo (boolean) – If True, if the command gets an exception, prepend sudo to the command and try again.

For the other parameters, see subprocess.check_output().

Returns:

str – Captured stdout/stderr from the command

Raises:

• HelperNotFoundError – if the command doesn’t exist (instead of a OSError)
• HelperError – if require_success is not False and the command returns a value other than 0 (instead of a subprocess.CalledProcessError).
• OSError – as subprocess.check_output().

helper_select(choices)

Select the first helper that is available from the given list.

If no helper in the list is currently installed, will install the first installable helper from the list.

Raises:HelperNotFoundError – if no valid helper is available or installable. Parameters:choices (list) –

List of helpers, in order from most preferred to least preferred. Each choice in this list can be either:

• a string (the helper name, such as “mkisofs”)
• a tuple of (name, minimum version) such as (“qemu-img”, “2.1.0”).

Returns:Helper – The selected helper class instance.

helpers = {'isoinfo': <COT.helpers.isoinfo.ISOInfo object at 0x7f6d11f805d0>, 'gcc': <COT.helpers.gcc.GCC object at 0x7f6d11f80590>, 'mkisofs': <COT.helpers.mkisofs.MkISOFS object at 0x7f6d11f80650>, 'make': <COT.helpers.make.Make object at 0x7f6d11f80610>, 'port': <COT.helpers.port.Port object at 0x7f6d11f80810>, 'qemu-img': <COT.helpers.qemu_img.QEMUImg object at 0x7f6d11f80750>, 'genisoimage': <COT.helpers.mkisofs.GenISOImage object at 0x7f6d11f80690>, 'yum': <COT.helpers.yum.Yum object at 0x7f6d11f80850>, 'fatdisk': <COT.helpers.fatdisk.FatDisk object at 0x7f6d11f80550>, 'vmdktool': <COT.helpers.vmdktool.VMDKTool object at 0x7f6d11f80790>, 'apt-get': <COT.helpers.apt_get.AptGet object at 0x7f6d11f807d0>, 'ovftool': <COT.helpers.ovftool.OVFTool object at 0x7f6d11f80710>, 'xorriso': <COT.helpers.mkisofs.XorrISO object at 0x7f6d11f806d0>}

Dictionary of concrete Helper subclasses to be populated at load time.