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
[source]¶ Bases:
exceptions.EnvironmentError
A helper program exited with non-zero return code.
-
exception
HelperNotFoundError
[source]¶ Bases:
exceptions.OSError
A helper program cannot be located.
-
class
Helper
(name, info_uri=None, version_args=None, version_regexp='([0-9.]+)')[source]¶ 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.]+)')[source]¶ Initializer.
Parameters:
-
_install
()[source]¶ Subclass-specific implementation of installation logic.
This method should only be called from
install()
, which does the appropriate pre-validation against theinstalled
andinstallable
properties before calling into this method if appropriate.
-
call
(args, capture_output=True, use_cached=True, **kwargs)[source]¶ 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 ofcheck_call()
) - use_cached (boolean) – If
True
, andcapture_output
is alsoTrue
, then if there is an entry incached_output
for the givenargs
, just return that entry instead of calling the helper again. Ignored ifcapture_output
isFalse
.
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, elseNone
.For the other parameters, see
check_call()
andcheck_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)[source]¶ Copy the given src to the given dest, using sudo if needed.
Parameters: Returns: bool – True
Raises: HelperError
– if file copying fails
-
static
download_and_expand_tgz
(*args, **kwds)[source]¶ 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
()[source]¶ Install the helper program.
Raises: NotImplementedError
– if notinstallable
on this platformRuntimeError
– if potentiallyinstallable
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)[source]¶ Check whether the given target directory exists, and create if not.
Parameters:
-
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)[source]¶ Bases:
dict
Dictionary of Helper objects by name.
Similar to
collections.defaultdict
but takes the key as a parameter to the factory.
-
class
PackageManager
(name, info_uri=None, version_args=None, version_regexp='([0-9.]+)')[source]¶ Bases:
COT.helpers.helper.Helper
Helper program with additional API method install_package().
-
check_call
(args, require_success=True, retry_with_sudo=False, **kwargs)[source]¶ 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, prependsudo
to the command and try again.
For the other parameters, see
subprocess.check_call()
.Raises: HelperNotFoundError
– if the command doesn’t exist (instead of aOSError
)HelperError
– ifrequire_success
is notFalse
and the command returns a value other than 0 (instead of asubprocess.CalledProcessError
).OSError
– assubprocess.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)[source]¶ 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, prependsudo
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 aOSError
)HelperError
– ifrequire_success
is notFalse
and the command returns a value other than 0 (instead of asubprocess.CalledProcessError
).OSError
– assubprocess.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)[source]¶ 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>, 'gcc': <COT.helpers.gcc.GCC object>, 'mkisofs': <COT.helpers.mkisofs.MkISOFS object>, 'make': <COT.helpers.make.Make object>, 'port': <COT.helpers.port.Port object>, 'qemu-img': <COT.helpers.qemu_img.QEMUImg object>, 'genisoimage': <COT.helpers.mkisofs.GenISOImage object>, 'yum': <COT.helpers.yum.Yum object>, 'fatdisk': <COT.helpers.fatdisk.FatDisk object>, 'vmdktool': <COT.helpers.vmdktool.VMDKTool object>, 'brew': <COT.helpers.brew.Brew object>, 'apt-get': <COT.helpers.apt_get.AptGet object>, 'ovftool': <COT.helpers.ovftool.OVFTool object>, 'xorriso': <COT.helpers.mkisofs.XorrISO object>}¶ Dictionary of concrete Helper subclasses to be populated at load time.