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.
_install	Subclass-specific implementation of installation logic.
unsure_how_to_install	Return a RuntimeError or NotImplementedError for install trouble.

__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.

_install()

Subclass-specific implementation of installation logic.

This method should only be called from install(), which does the appropriate pre-validation against the installed and installable properties before calling into this method if appropriate.

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 on this platform
• RuntimeError – if potentially installable on this platform but required helpers (e.g., package managers) are not available.
• 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()

Return a RuntimeError or NotImplementedError for install trouble.

USER_INTERFACE = <COT.cli.CLI object>

User interface (if any) available to helpers.

_provider_package = {}

Mapping of package manager name to package name to install with it.

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, or a list of parameters used to install the package.

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().

Examples

>>> check_call(['true'])
>>> try:
...     check_call(['false'])
... except HelperError as e:
...     print(e.errno)
...     print(e.strerror)
1
Helper program 'false' exited with error 1
>>> check_call(['false'], require_success=False)
>>> try:
...     check_call(['/non/exist'])
... except HelperNotFoundError as e:
...     print(e.errno)
...     print(e.strerror)
2
Unable to locate helper program '/non/exist'. Please check your $PATH.
>>> try:
...     check_call(['/etc/'])
... except OSError as e:
...     print(e.errno)
...     print(e.strerror)
13
Permission denied

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().

Examples

>>> output = check_output(['echo', 'Hello world!'])
>>> assert output == "Hello world!\n"
>>> try:
...     check_output(['false'])
... except HelperError as e:
...     print(e.errno)
...     print(e.strerror)
1
Helper program 'false' exited with error 1:
> false

>>> output = check_output(['false'], require_success=False)
>>> assert output == ''
>>> try:
...     check_output(['/non/exist'])
... except HelperNotFoundError as e:
...     print(e.errno)
...     print(e.strerror)
2
Unable to locate helper program '/non/exist'. Please check your $PATH.
>>> try:
...     check_output(['/etc/'])
... except OSError as e:
...     print(e.errno)
...     print(e.strerror)
13
Permission denied

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 0x7f02fb64a710>, 'gcc': <COT.helpers.gcc.GCC object at 0x7f02fb64a6d0>, 'mkisofs': <COT.helpers.mkisofs.MkISOFS object at 0x7f02fb64a790>, 'make': <COT.helpers.make.Make object at 0x7f02fb64a750>, 'port': <COT.helpers.port.Port object at 0x7f02fb64a990>, 'qemu-img': <COT.helpers.qemu_img.QEMUImg object at 0x7f02fb64a890>, 'genisoimage': <COT.helpers.mkisofs.GenISOImage object at 0x7f02fb64a7d0>, 'yum': <COT.helpers.yum.Yum object at 0x7f02fb64a9d0>, 'fatdisk': <COT.helpers.fatdisk.FatDisk object at 0x7f02fb64a690>, 'vmdktool': <COT.helpers.vmdktool.VMDKTool object at 0x7f02fb64a8d0>, 'brew': <COT.helpers.brew.Brew object at 0x7f02fb64a950>, 'apt-get': <COT.helpers.apt_get.AptGet object at 0x7f02fb64a910>, 'ovftool': <COT.helpers.ovftool.OVFTool object at 0x7f02fb64a850>, 'xorriso': <COT.helpers.mkisofs.XorrISO object at 0x7f02fb64a810>}

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