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

copy_file	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, use_cached=True, **kwargs)

Call the helper program with the given arguments.

Parameters:

• args (tuple) -- 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())
• use_cached (boolean) -- If True, and capture_output is also True, then if there is an entry in cached_output for the given args, just return that entry instead of calling the helper again. Ignored if capture_output is False.

Note

By default no captured output is cached (as it may not necessarily be appropriate to cache the output of many commands.) Subclasses that wish to cache output of certain calls should wrap this method with the appropriate logic, typically along the lines of:

output = super(MyHelper, self).call(args, *kwargs)
if output and args[0] == 'info':
    self.cached_output[args] = output
return output

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 copy_file(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.ui.cli.CLI object>

User interface (if any) available to helpers.

_provider_package = {}

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

cached_output = None

Cache of call args --> output from this call.

This is opt-in per-subclass - nothing is cached by default.

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 = {'apt-get': <COT.helpers.apt_get.AptGet object at 0x7f50d9fa4390>, 'brew': <COT.helpers.brew.Brew object at 0x7f50d9fa43d0>, 'fatdisk': <COT.helpers.fatdisk.FatDisk object at 0x7f50d9fa4110>, 'gcc': <COT.helpers.gcc.GCC object at 0x7f50d9fa4150>, 'genisoimage': <COT.helpers.mkisofs.GenISOImage object at 0x7f50d9fa4250>, 'isoinfo': <COT.helpers.isoinfo.ISOInfo object at 0x7f50d9fa4190>, 'make': <COT.helpers.make.Make object at 0x7f50d9fa41d0>, 'mkisofs': <COT.helpers.mkisofs.MkISOFS object at 0x7f50d9fa4210>, 'ovftool': <COT.helpers.ovftool.OVFTool object at 0x7f50d9fa42d0>, 'port': <COT.helpers.port.Port object at 0x7f50d9fa4410>, 'qemu-img': <COT.helpers.qemu_img.QEMUImg object at 0x7f50d9fa4310>, 'vmdktool': <COT.helpers.vmdktool.VMDKTool object at 0x7f50d9fa4350>, 'xorriso': <COT.helpers.mkisofs.XorrISO object at 0x7f50d9fa4290>, 'yum': <COT.helpers.yum.Yum object at 0x7f50d9fa4450>}

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